phpDocumentor или как правильно составить документацию

[DSii]

phpDocumentor или как правильно составить документацию

Доброго времени суток, Господа!

На повестке дня вопрос о правильном составлении документации к проекту с помощью phpDocumentor.

Собственно в этом и вопрос - подскажите, как им правильно пользоваться, есть ли какие-то рекомендации о верном владении этим инструментом, как нужно организовать package, subpackage и category?

Буду примного благодарен откликнувшимся \

 

[Alexandre]

phpDocumentor или как правильно составить документацию

вопрос, какую документацию?

phpDocumentor предназначен для составления документации по ходу разработки. как конечный продукт - может быть документация по API, но не более того.

 

[DSii]

Alexandre
Вобщем-то вы правильно все поняли, составление документации по API приложения
То есть вопрос в том, как правильно ее составлять в ходе разработки, чтобы она была как можно содержательнее/понятнее/удобнее при работе, а так же всего того, что написал в первом своем посте...

 

[Alexandre]

в доке все написано,
из собственных правил:
1) АПИ разбить на пакеты и подпакеты, у меня например были:
- core
- core.DB (классы работы с БД)
- CZ
- CZ.admin (подпакет admin пакета CZ)
...
2) описать каждый файл (начальное описание файла, к какому пакету принадлежит, состав пакета - необязательно )
3) документировать каждый класс (начальное описание класса, принадлежность к пакету, зачем нужен....)
4) документировать каждый публичный метод класса, можно некоторые приватные
5) документировать все константы

к сожалению я не нашел опцию, как вставить в index.html свою информацию (например README) куда бы хорошо впихнуть общее описание архитектуры, задумки и т.д.
использовать опцию - документация с источниками.

сам документатор очень удобен, когда идет групповая разработка,
документация собирается в фоне (по крону) и ты видишь, что реализованно, а что нет,
всегда можно посмотреть "текущие" источники реализации того или иного метода.

вот интересный пост

 

[DSii]

Alexandre
Огромное спасибо, но есть еще вопрос...
Использовали вы @category и в чем с ним трюк?
Когда я его использую в док-комментариях, при генерации документации у меня появляются ошибки в отчете phpDocumentor и сами категории он не подхватывает. Прописывал ровно, как в документации к phpDocumentor, но та же петрушка... (

 

[Alexandre]

Использовали вы @category и в чем с ним трюк?

сорри, не исп.