Вам следует попробовать Плагин Api Generator (, представленный здесь ), используемый для питания официального CakePHP API .
. Используется Класс отражения (доступно в PHP 5.2 и более поздних версиях) для динамического анализа комментариев docblock вашего кода , означающих, что вам не нужно заново генерировать документацию для каждого внесенного изменения.
Есть также несколько дополнительных функций, таких как индексация поиска, вычисление охвата документации вашего кода и возможность использования Markdown в комментариях к вашему докблоку для генерации HTML в вашей документации.
Вы всегда можете использовать общие решения, применимые к любой кодовой базе PHP, например, phpDocumentor или doxygen .
Вам нужно будет добавить докблоки в вашкод с соответствующими тегами для работы любого из этих решений (некоторые IDE могут сгенерировать их для вас). основной код CakePHP (и связанная документация ) может использоваться в качестве хорошего примера того, что требуется.
Несколько тонких стандартов, которые я заметил, команда CakePHP используетпри документировании кода:
- Никогда не вставляйте отступ в комментарии к докблоку, даже внутри класса.Это позволяет прокручивать сканирование кода по docblock, а также позволяет вводить ширину по горизонтали каждой строки (обычно около 100 символов).
- Завершите каждое предложение точкой (или точкой), как этодействует как хороший сигнал, чтобы вы знали, является ли каждая часть документации полной и продуманной.