Как просмотреть комментарии jsdoc в сценариях документов Google

Обновление 2014. Теперь, когда библиотеки поддерживаются функцией автозаполнения редактора скриптов Google Apps, можно получить немедленный отзыв о НЕКОТОРЫХ комментариях jsdoc вашей библиотеки.

Это решение не идеально — оно не выглядит так же, как опубликованные библиотеки сценариев Google, — но, по крайней мере, я могу работать с комментариями jsdoc, чтобы получить хорошее представление о том, как они будут выглядеть, без постоянного создания новых версий моих библиотека без функциональных расширений. Если кто-то может подробно описать дополнительные шаги для получения точных результатов, которые мы увидим при публикации, поделитесь, пожалуйста!

Это то, что я сделал на ПК с Windows 7. Аналогичные шаги могут работать и на других платформах, ymmv.

• Получите jsdoc3, загрузив репозиторий в виде zip-файла.

• Распаковать в удобное место. Я использовал C:\jsdoc. При этом также устанавливается Rhino jvm, необходимый для jsdoc3.

Затем вам нужно поместить свой скрипт Google в локальный файл, который может быть проанализирован jsdoc3. Опять же, если кто-то знает лучший способ, я весь внимание!

• Настройте локальный каталог для вашего проекта скрипта Google. C:\myscript, скажем.

• Перейдите к своему скрипту в google docs/drive/whatever и скопируйте все это в системный буфер обмена.

  <ctrl-A> <ctrl-C>
  

• Используя ваш любимый текстовый редактор, вставьте содержимое буфера обмена

  <ctrl-V>
  

• Сохраните результаты в файле javascript. C:\myscript\testing.js, скажем.

Итак, теперь нужно проанализировать файл, проверить вывод и отредактировать комментарии jsdoc до тех пор, пока они вас не устроят.

Вывод jsdoc3 попадет в каталог «out».

• Откройте командное окно в C:\myscript.

• Разберите ваш файл javascript.

  \jsdoc\jsdoc testing.js
  

• Откройте вывод в браузере по умолчанию.

  out\index.html
  

• Смойте и повторяйте, пока не получите желаемый результат.

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

Предостережения:

• Формат вывода отличается от того, который вы увидите в опубликованной библиотеке скриптов Google, но содержание в основном такое же. Помните, что Google поддерживает только часть тегов jsdoc (только (@param и @returns) — вы можете поместить в свой код другие теги, но они будут проигнорированы.

• Таблицы HTML могут быть включены в ваши комментарии jsdoc с ограниченными возможностями настройки.

  • You must enclose ALL rows in <tbody></tbody> tags; rows within <thead> get ignored.
  • Далее - все <th> игнорируются. Чтобы выделить первую строку, используйте теги <b></b>.
  • Не беспокойтесь о форматировании ячеек, align и т. д. будут проигнорированы.
  • Вы можете указать ширину в атрибуте стиля, и он сохранится.

Пример:

Вот пример некоторых элементов, которые отображаются как в jsdoc, так и в googlescript doc:

/**
 * Demonstrate jsdoc with a table. Otherwise, meaningless gibberish.
 *
 * <table> 
 * <tbody>
 * <tr><td style="width: 75%"><b>Student Name</b></td><td style="width: 25%"><b>Idiocy Factor</b></td></tr>
 * <tr><td> John Smith      </td><td align=right>  18 </td></tr>
 * <tr><td> Sally Doe       </td><td align=right>  53 </td></tr>
 * <tr><td> Carmen Sandiego </td><td align=right>  90 </td></tr>
 * <tr><td> Tam O'Shanter   </td><td align=right> 180 </td></tr>
 * </tbody>
 * </table>
 *
 * Continuation of function description down here. Why not have an example?
 * <pre>
 * =myFunc($A8, $DV8 )
 * </pre>
 *
 * @param {String} your mother's name, e.g. <code>"Anne Murray"</code>
 * @param {String} date of birth, <code>DD/MM/YYYY</code>
 * @returns {Date} estimated date of demise
 * @returns {String} "Please try again." if error in input
 */

Не идеально, и с довольно высоким значением PITA. Тем не менее, jsdoc позаботится о том, чтобы вы правильно поняли синтаксис любых неподдерживаемых тегов, что отлично подходит для переносимости.