Как просмотреть комментарии jsdoc в скриптах Google doc

Question

Я знаю, что возникла проблема 1731 с запросом предварительного просмотра jsdoc в редакторе сценариев Google. http://code.google.com/p/google-apps-script-issues/issues/detail?id=1731

Пока мы ждем, чтобы это было реализовано, как лучше всего просмотреть комментарии jsdoc, которые я добавляю в свою опубликованную библиотеку, не требуя от меня создания новой версии?

Answer 1

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

---

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

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

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

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

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

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

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

  <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 Script, но содержание в основном такое же. Помните, что Google поддерживает только подмножество тегов jsdoc (только @param и @returns) - вы можете добавить другие в свой код, но они будут игнорироваться.

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

  • Вы должны заключить ВСЕ строки в <tbody></tbody> теги; строки в <thead> быть проигнорированным
  • Дальше - все <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 обеспечит правильный синтаксис любых неподдерживаемых тегов, что очень удобно для переносимости.