Как вы документируете API?

Question

[Mike Evstropov]

К примеру, мы пишем некую программу, и разумеется, все комментируется в коде. Отдельно мы можем структурировать все доступные интерфейсы и типы данных которые могут приниматься, к примеру в gedit, notepad, textmate или где-то еще. Но, есть ли сервисы или решения, которые помогают в этом? Хочется красиво и упорядочено организовать документацию. Так же, было бы здорово, поинтересоваться как решаете этот вопрос именно Вы.

Answer 1

[DevMan]

для внутреннего потребления - генерируем документацию по комментариям.
для внешнего потребления - первый пункт доводится до нужного состояния специальными людьми.

Comments

[DevMan]

Mike Evstropov судя по вашим вопросам предположу, что используете PHP. тогда вам прямая дорога к https://ru.wikipedia.org/wiki/PhpDocumentor если грамотно подойти, то можно обойтись и без специальных людей.

да я и для других языков подход аналогичный.

также есть категория специалистов, которые всю документацию пишут исключительно руками (для этого есть несколько систем/сервисов, как платных так и бесплатных). но как по мне, это перебор.

[Mike Evstropov]

Вопрос встал на js. Но по факту проблема глобальная, и там и там. Хотелось бы что-то, где можно строить список методов, типы возвращаемых/принимаемых данных, и делать это через gui. А PhpDocumentor сейчас буду смотреть =) Спасибо!

[DevMan]

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

для js есть jsdoc.

[DevMan]

Mike Evstropov: https://en.wikipedia.org/wiki/JSDoc

Answer 2

[Эдуард Тибет]

Но, есть ли сервисы или решения, которые помогают в этом?

doxygen?
swagger | blueprint | RAML (for REST API)?
single sourcing technical documentation?

Comments

[Mike Evstropov]

Все это здорово, и да, это ответ на вопрос. Только я, так и не познал дзен этого инлайн документирования. Накой черт мне разбираться во всяких шаблонизаторах, что бы на выходе иметь простенький хтмл. Это скорее для крупных проектов, где важна именно генерация доков, так как может быть куча версий и куча рук. Может есть какой-то вариант попроще?

[Эдуард Тибет]

Mike Evstropov: Прошу прощения, но я специлизируюсь только на сложных вещах :)
Попроще... https://readthedocs.org/ ? Что-нибудь из разряда: .rst, .md, .adoc Но здесь, конечно, речь идет о "ручном" написании, а не генерации из кода.

Дело в том, что если вы стартап - то да, сложные решения сложны для вас. НО, ведь каждый стартап хочет перерасти посевную фазу и вырасти во что-то приличное. Значит при выборе нужного средства (даже простого на первом этапе) вам в любом случае надо думать о возможном масштабировании вопроса.

[Mike Evstropov]

Воот. То что нужно. =) Просто, в моем случае это выглядело бы так же, как некоторые плагинчики на js, общим весом в 20 килобайт, но б(ь мы же хипстеры, везде у нас package.json, gruntfile.js, bower.json, их еще собери попробуй... Ничего не имею против npm, но не в трех ста строк кода...