Комментарии 18
Немного сбило с толку:
Насколько я понял, у GitHub своя wiki-система, которая основана опять же на Git. В этой wiki хранят версии документов в Git, используют историю Git, git-diff и т.д.
Проект 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, похоже, есть.
jacobian.org/writing/great-documentation/what-to-write/
У меня по опыту то же самое — раньше пытался все генерировать, потом понял, что получается бесполезный хлам. Теперь вместо того, чтобы полагаться на такие инструменты, стараюсь писать хороший README с основными сценариями использования, и понятный код внутри, без выкрутасов и с комментариями.
Хотя к инструментам вроде Docco можно присмотреться. Еще рано говорить, хорошая это идея или нет, но определенная логика в том, чтобы делать документацию в стиле Docco, похоже, есть.
восновном — > в основном
Забавно, что свою докементацию я тоже писал, опираясь на jQuery/Ajax. Ещё как вариант рассматривал API Sendspace: www.sendspace.com/dev_method.html
Описание API фейсбука я отверг как сложное
Описание API фейсбука я отверг как сложное
Забыли пример документации для ExtJS, сделанный на ext-doc
Документация jQuery располагается по адресу docs.jquery.comИногда удобнее пользоваться непосредственно jQuery API
«Даже если ваш проект с закрытым исходным кодом» — на хуй такие проекты! И документация не поможет!!!
Раз пошли непонимания, поясни свою мысль. Я изобрел новое колесо и все знают его устройство, и какой-то умник его через полгода усовершенствовал и покатил быстрее. Он молодец — а я дурак, если я пол года нихера не делал, чтобы это вращалось еще быстрее. ПРИВЕТ УМНИКАМ И ИХ МИНУСАМ!!! 21 век! мы тупеем и жадность растет в прогрессии!!!
На мой взгляд, одна из самых удобных документация по API у ExtJS:
dev.sencha.com/deploy/dev/docs/
dev.sencha.com/deploy/dev/docs/
Использую JSDoc, потому что имеет javadoc синтаксис и jsdoc-toolkit имеет jar для ant.
За Dox и Docco огромное спасибо!
За Dox и Docco огромное спасибо!
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Написание документации