Pull to refresh
Comments 18
Немного сбило с толку:
Проект GitHub имеет wiki, которая генерируется движком Git.

Насколько я понял, у GitHub своя wiki-система, которая основана опять же на Git. В этой wiki хранят версии документов в Git, используют историю Git, git-diff и т.д.
Вот тут хорошие аргументы по поводу того, чем плоха автоматически сгенерированная из исходников (JSDoc, Javadoc, RDoc и т.д.) документация:
jacobian.org/writing/great-documentation/what-to-write/

У меня по опыту то же самое — раньше пытался все генерировать, потом понял, что получается бесполезный хлам. Теперь вместо того, чтобы полагаться на такие инструменты, стараюсь писать хороший README с основными сценариями использования, и понятный код внутри, без выкрутасов и с комментариями.

Хотя к инструментам вроде Docco можно присмотреться. Еще рано говорить, хорошая это идея или нет, но определенная логика в том, чтобы делать документацию в стиле Docco, похоже, есть.
Комментарии для обсуждения содержимого статьи. О грамматических ошибках принята писать в л/с.
Мудрый комментарий даже спустя пять лет будет мудрым
Забавно, что свою докементацию я тоже писал, опираясь на jQuery/Ajax. Ещё как вариант рассматривал API Sendspace: www.sendspace.com/dev_method.html
Описание API фейсбука я отверг как сложное
сорвалось… занимает при первой загрузке он около мегабайта, если предоставлять документацию открыто, то слишком грузно.
Документация jQuery располагается по адресу docs.jquery.com
Иногда удобнее пользоваться непосредственно jQuery API
«Даже если ваш проект с закрытым исходным кодом» — на хуй такие проекты! И документация не поможет!!!
Раз пошли непонимания, поясни свою мысль. Я изобрел новое колесо и все знают его устройство, и какой-то умник его через полгода усовершенствовал и покатил быстрее. Он молодец — а я дурак, если я пол года нихера не делал, чтобы это вращалось еще быстрее. ПРИВЕТ УМНИКАМ И ИХ МИНУСАМ!!! 21 век! мы тупеем и жадность растет в прогрессии!!!
Использую JSDoc, потому что имеет javadoc синтаксис и jsdoc-toolkit имеет jar для ant.
За Dox и Docco огромное спасибо!
Only those users with full accounts are able to leave comments. Log in, please.