JavaScript Самодокументирующийся код, где инструменты API Docs?

Эти две концепции кажутся нелогичными. Есть одна сторона аргумента, которая видит вред, который комментарии наносят удобочитаемости, и нарушения DRY (если комментарии даже поддерживаются в актуальном состоянии). Однако подбросьте монету: необходимо предоставить хорошую документацию по API для вашего кода, чтобы другие могли использовать ваши библиотеки.

Каждый инструмент (JSDoc, PDoc и т. д.), который я видел и который предназначен для создания документов API, использует очень много места для предоставления этой документации. Мне нужно предоставить документацию по API, чего мне не нужно, так это того, чтобы половина моего LOC была специально отформатирована с комментариями, чтобы JSDoc мог ее прочитать.

В настоящее время я рассматриваю базовый инструмент уценки, такой как Jekyll, и помещаю эту документацию в папку /doc, полностью удаляя это из моего кода. Кто-нибудь еще нашел подход к этой проблеме, который сработал для них?


javascript documentation-generation self-documenting-code
person Drew    schedule 17.03.2011    source источник
comment
Если вы используете сценарий сжатия во время сборки, вам действительно не нужно беспокоиться о дополнительных строках в вашем коде.   -  person epascarello    schedule 17.03.2011
comment
Полный акк. Если вы хотите предоставить документацию хорошего качества, она должна оставаться с исходным кодом. При использовании сжатого файла в продакшене (что вы должны делать в любом случае) комментарии вообще не имеют значения.   -  person Daff    schedule 17.03.2011
comment
Не беспокойтесь о производственных файлах, компрессоры их удалят. Мне нужны читаемые файлы, которые на 75% не являются специально отформатированными комментариями, чтобы какой-нибудь инструмент мог их прочитать.   -  person Drew    schedule 21.03.2011
comment
Я не могу достаточно проголосовать за этот вопрос. Похоже, что все инструменты документации JS не делают ничего полезного без специально отформатированных комментариев. И я согласен с ОП, я не хочу засорять свой источник гнилыми комментариями. Является ли динамическая природа JavaScript слишком сложной для таких инструментов?   -  person Allan    schedule 07.02.2014

Ответы (1)


arrow_upward
0
arrow_downward

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

Лично я считаю более удобным располагать документацию по API рядом с кодом, так как это помогает мне поддерживать ее в актуальном состоянии. Более того, другие люди, работающие над этим кодом, смогут получить документацию именно тогда, когда она им понадобится, без необходимости просмотра внешних файлов. Честно говоря, я не вижу ничего плохого в том, что большинство строк кода являются комментариями: редакторы обычно окрашивают комментарии по-разному и позволяют игнорировать их, если хотите.

person Andrea    schedule 17.03.2011
comment
Это выглядит довольно круто, если использовать внешние файлы. Тем не менее, я бы хотел придерживаться уценки для жалоб на кросс-инструмент, поскольку многие люди переходят на уценку. Может ли это анализировать файлы JavaScript? - person Drew; 21.03.2011
comment
Я не пробовал, но autodoc должен работать и с файлами Javascript. - person Andrea; 21.03.2011