Написание документации по API

Question

[p4s8x]

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

Хочется, чтобы были следующие функции:
— Автогенерация диаграммы классов из кода, дерево классов и т.п. — все что в коде в phpdoc-стиле
— Возможность написания мануалов вручную
— Автоматическая перелинковка между ручными мануалами и диаграммой классов.
— Возможность настраивать свои шаблоны генерации( т.е. так, чтобы из php классов\методов писалась документация внешнего API)

Пока смотрю на www.phpdoc.org/ + написать к ней плагин, шаблон + какаято вики, но может есть чтото готовое и удобное.

Поделитесь опытом ведения документации и особенно документирования API к своему проекту!

Answer 1

[Wott]

По опыту с другой стороны вся эта документация по классам не особенно и нужна — если надо, всегда можно в исходниках глянуть что к чему, но зачастую, для подстановки в IDE, декларации более чем достаточно.
Нужнее другая информация — зависимости вызовов через параметры, use cases, в крайнем случае примеры. Как правило это пара страничек текста, если без воды, но очень ценных страничек.

По опыту — делайте в wiki. Единственно что *doc надо скриптом в вики разметку перекидать, но потом с созданием ссылок и сопровождением проблем нет. Полностью готового не видел — все так или иначе либо тупо накидывают результаты выдачи php|javadoc, либо рисуют сами

Comments

[Денис Туренко]

Согласен, mediawiki+phpdoc. Сначала будет казаться, что много времени уйдет, но потом результат оправдает надежды.
По wiki вот отличный пост про ее настройки для команды редакторов habrahabr.ru/qa/26235/

Answer 2

[Сергей Береснев]

Тесты можно использовать как документацию.: )

Answer 3

[Сергей Протько]

На наших проектах документация к API для разработчиков генерируется автоматически (в случае с REST, примеры вызова методов через cURL, в случае с SOAP — особо и не нужно, WSDL хватает).