Javascript-форум (https://javascript.ru/forum/)
-   Оффтопик (https://javascript.ru/forum/offtopic/)
-   -   Вопросы по JSDoc (https://javascript.ru/forum/offtopic/40520-voprosy-po-jsdoc.html)

FINoM 08.08.2013 20:49

Вопросы по JSDoc
 
Всем привет.
Решил документировать свой код, но столкнулся с рядом проблем. В первую очередь у меня возникли вопросы с описанием объектов. Затем, когда я попытался сгенерировать тестовую документацию, у меня ничего не получилось. Поэтому, вопрос, для начала, касается генераторов.

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

Зайдя на эту страницу https://github.com/jsdoc3/jsdoc я выяснил, что мне, для начала, надо поставить https://github.com/hegemonic/rhino но там, к моему сожалению, не оказалось ни единого намёка на инструкцию по установке. Эту идею я оставил на потом, продолжив поиск альтернативного генератора.

Вторым кандидатом на генератор документации я выбрал http://www.seehuhn.de/pages/jvjsdoc . Проблем с установкой и запуском небыло (какие проблемы, если нужно всего лишь клонировать репозиторий и запустить файлик). Но меня разочаровало то, что я не смог найти возможности указать в качестве источника конкретные файлы, а не целую папку. Кстати, скрипт лез и в недокументированные места и попытался как-то криво сгенерировать доку и для них.

Третьим кандидатом был yuidocjs. Устанавливая его с помощью npm, получил кучу ошибок.

О том, что у меня руки из жопы растут, прошу на писать :)

В общем, первый вопрос: как сгенерировать документацию для конкретных файлов?

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

Спасибо.

monolithed 08.08.2013 21:40

Попробуй Doxygen :)

Tim 11.08.2013 21:49

Качаешь
https://code.google.com/p/jsdoc-toolkit/

Читаешь как сгенерировать
http://y3x.ru/2011/02/jsdoc-toolkit/

FINoM 24.08.2013 14:50

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();
...

FINoM 24.08.2013 15:04

(Решено: @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 - вот такое меню получается.

Tim 24.08.2013 16:02

FINoM,
Честно говоря я сам не сильно разбираюсь. Для себя чисто пару раз попробовал. На работе не требуется, по этому не использую.

FINoM 24.08.2013 20:24

К первому вопросу: как описать следующее свойство?
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 } ]

FINoM 25.08.2013 19:34

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

FINoM 25.08.2013 19:51

Цитата:

Сообщение от FINoM
Если я правильно понимаю, их должен поддерживать шаблон.

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

Tim 25.08.2013 20:00

Цитата:

Третьим кандидатом был yuidocjs. Устанавливая его с помощью npm, получил кучу ошибок.
О том, что у меня руки из жопы растут, прошу на писать
У меня очевидно от туда же. Не смог на винду его поставить.

FINoM 25.08.2013 21:12

Блин, фигня. Выбрал для вывода haruki (такой темплейт, который выводит доку в JSON или XML), массив examples остался пустым. Значит, я где-то с синтаксисом налажал.

Tim 05.09.2013 16:00

FINoM,
Если ты поднавтыкался уже, скинь пож-та пару примеров как аннотации писать в разных случаях. Мне тоже сейчас понадобилось неожиданно.

FINoM 05.09.2013 16:04

Tim, пока ничего не делал, но можно глянуть на мои вопросы на хабре: http://habrahabr.ru/users/finom/qa/questions/ (первые две штуки)

Tim 05.09.2013 16:27

FINoM,
Спс, пригодится.

Вот кст нашёл. На старой работе был семинар по этой теме PHPDoc, JSDoc.docx

Там пара интересных моментов про документирование jQuery плагинов

nerv_ 06.10.2013 04:14

Как в jsdocs сказать "второй и последующие параметры могут иметь произвольный тип"? Минимальное кол-во параметров - 1.

Tim 06.10.2013 13:24

Цитата:

Сообщение от nerv_
Как в jsdocs сказать "второй и последующие параметры могут иметь произвольный тип"? Минимальное кол-во параметров - 1.

Решил гуглнуть ради интереса. Вот что получилось:

Цитата:

Allows a parameter to be repeated
/**
 * Returns the sum of all numbers passed to the function.
 * @param {...number} num - A positive or negative number.
 */
function sum(num) {
    var i = 0, n = arguments.length, t = 0;
    for (; i < n; i++) {
        t += arguments[i];
    }
    return t;
}

пруф

Т.е. {...number} эта запись означает что параметр может повторяться. Произвольный тип это - *. + нужно сделать его не обязательным: {...*} [bar]. Т.е. что то такое:

@param {boolean} foo First parameter
@param {...*} [bar] Second parameter

Первый обязательный а второй нет и может повторяться. Думаю как то так, но не проверял.

nerv_ 06.10.2013 14:33

Tim, спасибо (карму не плюсует). Только, наверно, так:
Цитата:

Сообщение от Tim
// @param {...*} [bar] Second parameter

// @param {...*} [...] Second parameter

хотя, нет :)

Tim 06.10.2013 15:33

Цитата:

Сообщение от nerv_
карму не плюсует

Тогда верни мне мои 15 минут жизни бездарно потраченные на гугленье этой фигни :D

kobezzza 06.10.2013 15:41

Цитата:

Сообщение от nerv_ (Сообщение 275166)
Tim, спасибо (карму не плюсует). Только, наверно, так:
// @param {...*} [...] Second parameter

Смотря зачем ты пишешь jsdoc. Если для GCC, то

/**
 * @param {...*} foo
 */


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

Ман по стандарту гугла
https://developers.google.com/closur...s-for-compiler

nerv_ 07.10.2013 18:41

kobezzza, спс

Цитата:

Сообщение от Tim
Тогда верни мне мои 15 минут жизни бездарно потраченные на гугленье этой фигни

фсе претензии к владельцу ресурса :)

Vantedur 08.10.2013 01:34

Я чуствую что единственный действенный способ документирования кода это создание сайта аналогичного сайту jquery, все остальные подхоты в конце концов или растают или сгнеют

nerv_ 06.11.2013 17:30

Функция, принимающая один параметр переменного типа
 
Всем привет

Подскажите, как написать доку к функции, которая вызывается с одним аргументом, но этот аргумент переменного типа:

1.
/**
* @param {String} id
*/
function Foo( id ) { /* ... */ }


2.
/**
* @param {HTMLDivElement} div
*/
function Foo( div ) { /* ... */ }

kobezzza 06.11.2013 20:08

nerv, в синтаксисе гугла так:

/**
* @param {(HTMLDivElement|string)} divOrId 
*/
function Foo( divOrId ) { /* ... */ }


Если типов много, то с помощью typedef директивы можно создать псевдоним. Также можно использовать: * - любой тип или ? - тип неизвестен

nerv_ 06.11.2013 22:18

kobezzza, спасибо

Antonius 18.12.2013 04:13

Думал создавать отдельную тему, но тут обсуждается как раз то, что надо :)

Поэтому я к вам.

Есть структура данных (объект), классический пример — координаты. В скрипте во многих местах функции принимают в качестве аргумента или возвращают объекты этого формата. При том, что это просто структура — не имеет конструктора, в чистом виде нигде не встречается.

Хочется где-то описать ее, например «coordObject — это объект, содержащий поля x (вещественное число) и y (вещественное число), необязательное поле z (вещественное число) используется для описания трехмерных координат». Затем при описании параметров или возвращаемых значений хочется просто делать ссылку на описание этого формата.

Спасибо. Если это есть в документации, а я не нашел, не увидел или не понял, что это — оно, киньте в меня соответствующей ссылкой, пожалуйста.

Antonius 18.12.2013 04:41

Стоило только спросить — нашел.

http://usejsdoc.org/tags-typedef.html

Вопрос снят, всем спасибо.


Часовой пояс GMT +3, время: 07:22.