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

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

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

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

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

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

для js есть jsdoc.

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

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

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

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

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