Вопросы по JSDoc
Всем привет.
Решил документировать свой код, но столкнулся с рядом проблем. В первую очередь у меня возникли вопросы с описанием объектов. Затем, когда я попытался сгенерировать тестовую документацию, у меня ничего не получилось. Поэтому, вопрос, для начала, касается генераторов. Сразу скажу, что, хотя я и ношу звание программиста, у меня довольно часто возникают проблемы с установкой и использованием чего-либо нового. В качестве образовательной машины приобрел Raspberry PI, дабы перестать бояться командной строки, научиться устанавливать и настраивать серверные штуки, запустить синхронизацию рабочих проектов. Зайдя на эту страницу https://github.com/jsdoc3/jsdoc я выяснил, что мне, для начала, надо поставить https://github.com/hegemonic/rhino но там, к моему сожалению, не оказалось ни единого намёка на инструкцию по установке. Эту идею я оставил на потом, продолжив поиск альтернативного генератора. Вторым кандидатом на генератор документации я выбрал http://www.seehuhn.de/pages/jvjsdoc . Проблем с установкой и запуском небыло (какие проблемы, если нужно всего лишь клонировать репозиторий и запустить файлик). Но меня разочаровало то, что я не смог найти возможности указать в качестве источника конкретные файлы, а не целую папку. Кстати, скрипт лез и в недокументированные места и попытался как-то криво сгенерировать доку и для них. Третьим кандидатом был yuidocjs. Устанавливая его с помощью npm, получил кучу ошибок. О том, что у меня руки из жопы растут, прошу на писать :) В общем, первый вопрос: как сгенерировать документацию для конкретных файлов? После этого, хотелось бы получить ответы на ряд вопросов самого процесса документирования (например, как описать объект, в котором, под произвольными ключами, лежат объекты одной структуры). Спасибо. |
Попробуй Doxygen :)
|
Качаешь
https://code.google.com/p/jsdoc-toolkit/ Читаешь как сгенерировать http://y3x.ru/2011/02/jsdoc-toolkit/ |
Tim, спасибо, получилось. У меня есть несколько вопросов:
1. Как описать объект-коллекцию других однотипных объектов (определяемых в процессе работы скрипта)? Class({ myCollection: { a: { element: $( '.a' ), value: 2, getter: function() {} }, b: { element: $( '.b' ), value: 4, getter: function() {} } // , ... } }) 2. Как описать функцию (метод), принимающую разные аргументы (ключ + значение + опции, объект + опции, массив объектов...), часть из которых опциональны, а иногда и вовсе есть возможность не передавать аргументы? f(key, value); f(object); f(key); f(object,options); f(key,value,options); f(); ... |
(Решено: @method TopClass#on)
3. Как определить "контекст" документированного метода. Сейчас методы on и once попали в Global ( function( gc ) { /** * @class * @classdesc Does awesome stuff */ gc.TopClass = Class({ /** * @method on * @param {string|array} names * @param {function} callback * @param {boolean} triggerOnInit * @param {object} context */ on: function ( names, callback, triggerOnInit, context ) {}, /** * @method once * @param {string|array} names * @param {function} callback * @param {object} context */ once: function ( names, callback, context ) {} }); })( this ); http://take.ms/nRL3Pq - вот такое меню получается. |
FINoM,
Честно говоря я сам не сильно разбираюсь. Для себя чисто пару раз попробовал. На работе не требуется, по этому не использую. |
К первому вопросу: как описать следующее свойство?
Class({ prop: {a: [f1, f2, f3, f4], b: [f5, f6], c: [f7, f8, f9, f10, f11, f12], d:[]} }) Где fX - функции Upd: даже не так. fX - объект с фиксированной структурой: {f, ctx, name} prop object { array [ object { f: f, ctx: object, name: x } ] |
4. Почему может не показываться содержимое тега @example и @desc (независимо от того, где они размещаются)? Если я правильно понимаю, их должен поддерживать шаблон. Если так, подскажите, пожалуйста правильный шаблон.
/** * @method TC#on - The method adds events that could be triggered by TC#trigger method * @param {string} names - Names of the events * @param {function} callback - Event handler * @param {boolean} [triggerOnInit] - If equals to true then event handler will be triggered immediately * @param {object} [context] - "this" context for the handler * @returns {object} - self * @example * //Returns this * this.on( 'change:x', function() { * alert( 'x is changed' ); * }); * @example * //Returns this too. Alert will be execuded in window context and show secons argument, that has been passed to .trigger method ('Hello world') * this.on( 'ohmygosh', alert, window ); * this.trigger( 'ohmygosh', 'Hello world' ); * @example * //Shows "bar" alert immediately and waits for triggering "foo" event * this.on( 'foo', function() { * alert( 'bar' ); * }, true ) * @desc blah. * */ 5. Почему документация к методам генерируется не в том порядке, в котором методы объявлены? |
Цитата:
|
Цитата:
|
Блин, фигня. Выбрал для вывода haruki (такой темплейт, который выводит доку в JSON или XML), массив examples остался пустым. Значит, я где-то с синтаксисом налажал.
|
FINoM,
Если ты поднавтыкался уже, скинь пож-та пару примеров как аннотации писать в разных случаях. Мне тоже сейчас понадобилось неожиданно. |
Tim, пока ничего не делал, но можно глянуть на мои вопросы на хабре: http://habrahabr.ru/users/finom/qa/questions/ (первые две штуки)
|
FINoM,
Спс, пригодится. Вот кст нашёл. На старой работе был семинар по этой теме PHPDoc, JSDoc.docx Там пара интересных моментов про документирование jQuery плагинов |
Как в jsdocs сказать "второй и последующие параметры могут иметь произвольный тип"? Минимальное кол-во параметров - 1.
|
Цитата:
Цитата:
Т.е. {...number} эта запись означает что параметр может повторяться. Произвольный тип это - *. + нужно сделать его не обязательным: {...*} [bar]. Т.е. что то такое: @param {boolean} foo First parameter @param {...*} [bar] Second parameter Первый обязательный а второй нет и может повторяться. Думаю как то так, но не проверял. |
Tim, спасибо (карму не плюсует). Только, наверно, так:
Цитата:
// @param {...*} [...] Second parameter хотя, нет :) |
Цитата:
|
Цитата:
/** * @param {...*} foo */ А если для докогенератора, то нужно смотреть его синтаксис. Я юзаю гугловский стандарт JSDoc (он немного отличается), а для генерации доки написал свой движок. Ман по стандарту гугла https://developers.google.com/closur...s-for-compiler |
kobezzza, спс
Цитата:
|
Я чуствую что единственный действенный способ документирования кода это создание сайта аналогичного сайту jquery, все остальные подхоты в конце концов или растают или сгнеют
|
Функция, принимающая один параметр переменного типа
Всем привет
Подскажите, как написать доку к функции, которая вызывается с одним аргументом, но этот аргумент переменного типа: 1. /** * @param {String} id */ function Foo( id ) { /* ... */ } 2. /** * @param {HTMLDivElement} div */ function Foo( div ) { /* ... */ } |
nerv, в синтаксисе гугла так:
/** * @param {(HTMLDivElement|string)} divOrId */ function Foo( divOrId ) { /* ... */ } Если типов много, то с помощью typedef директивы можно создать псевдоним. Также можно использовать: * - любой тип или ? - тип неизвестен |
kobezzza, спасибо
|
Думал создавать отдельную тему, но тут обсуждается как раз то, что надо :)
Поэтому я к вам. Есть структура данных (объект), классический пример — координаты. В скрипте во многих местах функции принимают в качестве аргумента или возвращают объекты этого формата. При том, что это просто структура — не имеет конструктора, в чистом виде нигде не встречается. Хочется где-то описать ее, например «coordObject — это объект, содержащий поля x (вещественное число) и y (вещественное число), необязательное поле z (вещественное число) используется для описания трехмерных координат». Затем при описании параметров или возвращаемых значений хочется просто делать ссылку на описание этого формата. Спасибо. Если это есть в документации, а я не нашел, не увидел или не понял, что это — оно, киньте в меня соответствующей ссылкой, пожалуйста. |
|
Часовой пояс GMT +3, время: 07:22. |