Вопросы по 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. Почему документация к методам генерируется не в том порядке, в котором методы объявлены?

Таки да, в этом проблема. На usejsdoc.com есть описание этого тега, но в jsdoc3 его, как и многих других, нет. Не понимаю... Как официальная утилита может не поддерживать большую часть из того, что описано в официальной документации.

У меня очевидно от туда же. Не смог на винду его поставить.