JSDoc. Почему не обрабатывается тег @example?

Question

[Finom]

Знакомлюсь с документированием кода. Неотъемлемой частью почти любой документации являются примеры. Но почему-то они не попадают в сгенерированную страницу (так же, как и 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.
	 * 
	*/

Кроме дефолтного шаблона JSDoc3, я попробовал шаблон haruki, который генерирует xml или json. Массив example почему-то пуст.

  "functions": [
                {
                    "name": "on",
                    "access": "",
                    "virtual": false,
                    "description": "The method adds events that could be triggered by TC#trigger method only once.",
                    "parameters": [
                        {
                            "name": "names",
                            "type": "string",
                            "description": "Names of the events",
                            "default": "",
                            "optional": "",
                            "nullable": ""
                        },
                        {
                            "name": "callback",
                            "type": "function",
                            "description": "Event handler",
                            "default": "",
                            "optional": "",
                            "nullable": ""
                        },
                        {
                            "name": "triggerOnInit",
                            "type": "boolean",
                            "description": "If equals to true then event handler will be triggered immediately",
                            "default": "",
                            "optional": true,
                            "nullable": ""
                        },
                        {
                            "name": "context",
                            "type": "object",
                            "description": "\"this\" context for the handler",
                            "default": "",
                            "optional": true,
                            "nullable": ""
                        }
                    ],
                    "examples": [],
                    "returns": {
                        "type": "object",
                        "description": "- self"
                    }
                },...
}

Косяк с синтаксисом? Я пробовал пихать example наверх, результат тот же.

Спасибо.

Answer 1

[m03r]

У меня в JSDoc3 вообще не удавалось получить выход из Вашего комментария до тех пор, пока я не заменил @mеthod на @desc. Тогда весь вывод, включая примеры, был. Мой код, который даёт корректный выход:

Скрытый текст

/** 
 * @method
 * @desc Book#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 )
 * 
 */
function on(names, callback, triggerOnInit, context) {
  return 'blah';
}

Comments

[Finom]

Спасибо огромное. Вы мне спасли кучу времени, я уже свой парсер писать собирался, так как ни на гитхабе генератора, ни на официальном форуме мне не ответили.

[m03r]

Пожалуйста! Сам JSDoc'ом, честно говоря, очень давно не пользовался — хоть вспомнил, как он работает.

[Finom]

Угу. Очень неудобно иметь документацию и код в разных местах.