При создании javascript-библиотеки, где хорошее место для документирования API?

Я создаю библиотеку для создания пользовательского контента. Это довольно многословное, около 1100 строк кода. Хотя код очень читабельен и соответствует строгим соглашениям об именах, я не уверен, где документировать доступный API при включении файла сценария. При включении скрипта на странице intellisense не подбирает «общедоступные» методы и не делает это для jQuery. jQuery имеет потрясающий веб-сайт для своего API (http://api.jquery.com/), но я не чувствую себя склонным к тому, чтобы сделать что-то такое потрясающее.При создании javascript-библиотеки, где хорошее место для документирования API?

Где я должен документировать этот пользовательский API?

Если в комментариях, то какая структура комментариев вы бы предложили?

Редактировать

Моя точка для IntelliSense, что даже хорошие соглашения об именовании собираются требовать документированный API. Поэтому я определенно интересуюсь общим подходом.

источник

2012-05-15 Travis J

Прошу прокомментировать, если вы хотите, чтобы я добавил или изменил что-то для всех. В противном случае, пожалуйста, напишите как ответ, чтобы я мог присудить кредит. –

Вы просто ищете поддержку Visual Studio IntelliSense или что-то более общее? –

Я думаю, что комментирование должно выполняться во время кодирования, а не после ... удачи, понимая ваш код сейчас: s – ajax333221

Это не общий, но если вы не возражаете поддерживать отдельные версии для разных редакторов, IntelliSense Visual Studio будет загружать и анализировать комментарии XML в вашем JavaScript-коде.Я бы предположил, что MonoDevelop и SharpDevelop могут использовать тот же файл, но я не думаю, что IDE, такие как IntelliJ или Eclipse, получат от этого выгоду ...

HTH.

источник

2012-05-15 23:10:47

Я больше думал о том, как показать, что было доступно без чтобы играть или проверять слишком много. В качестве примечания для комментариев о intellisense, vs действительно хорош в этом. По вашему мнению, место недостижимого блока if (false) {} ', а затем внутри него ссылается на скрипт. Intellisense автоматически выполнит свою работу (возможно, вам придется сменить j, чтобы перезагрузить). –

Я выбрал это как ответ, потому что он указал мне на комментирование комментариев XML, что на самом деле довольно удивительно. –

Я думаю, что jsdoc довольно популярен.

http://code.google.com/p/jsdoc-toolkit/

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

Edit, вы можете также найти другие варианты здесь: http://o2js.com/2011/05/01/how-to-document-a-javascript-framework/

источник

2012-05-15 23:03:26 hvgotcodes

это зависит, насколько сложным ваш апи есть, для моих собственных маленьких библиотек я просто сделать большой комментарий в верхней части файла, содержащего

быстро рецензия, что это все о
, если библиотека работает на HTML разметке некоторые примеры кода, может быть скопирована & вставили
список функций с их параметрами и одной строки документации для каждого
примеров того, как библиотека обычно используется
примечания/предупреждения/ограничения. всегда есть что-то странное, люди не ожидают

В основном это то, что вы положили в заголовочный файл C.

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

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

источник

2012-05-15 23:06:57 kritzikratzi

При создании javascript-библиотеки, где хорошее место для документирования API?

ответ

Смежные вопросы