Finom
@Finom

JSDoc. Почему не обрабатывается тег @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.
	 * 
	*/


Кроме дефолтного шаблона 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 наверх, результат тот же.

Спасибо.
  • Вопрос задан
  • 2907 просмотров
Решения вопроса 1
m03r
@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';
}
Ответ написан
Пригласить эксперта
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы