如何在Google Doc脚本中预览jsdoc注释 [英] How to preview jsdoc comments in google doc scripts

问题描述

我知道1731号问题已经提出，要求在Google脚本编辑器中预览jsdoc。 http://code.google.com/p / google-apps-script-issues / issues / detail？id = 1731

当我们等待它被实现时，预览的最佳方式是什么jsdoc评论说我添加到我发布的库中，而不需要我创建新版本？现在由Google Apps脚本编辑器的自动完成支持的库，可以立即获得有关库的某些jsdoc注释的反馈。

---

这个解决方案并不理想 - 它没有提供与已发布的google脚本库相同的外观 - 但至少我可以通过我的jsdoc评论来了解它们的外观，而不是不断创建新版本我的库没有功能增强。 如果有人可以详细说明额外的步骤以获得我们从发布中看到的确切输出，请分享！

这就是我所知道的在Windows 7电脑上完成。类似的步骤可能适用于其他平台，ymmv。

• 通过以 zipfile 。
  

• 解压缩到一个方便的位置。我用 C：\ jsdoc 。这也安装了jsdoc3所需的Rhino jvm。

接下来，您需要将您的Google脚本变成本地文件，可以由jsdoc3解析。再一次，如果有人知道更好的办法，我会全力以赴！

• 设置一个您的谷歌脚本项目的本地目录。 C：\ myscript ，说。

，并将整个事件复制到系统剪贴板中。



 < 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空间，验证您的代码没有损坏，然后创建一个新版本来为您发布的库生成文档。


$ b

警告：







• 输出格式与您在发布了Google Script Libary，但内容大致相同。请记住，Google仅支持jsdoc标签的一个子集（仅限于@param和@returns） - 您可以将其他代码放入代码中，但它们将被忽略。

HTML表格可以包含在jsdoc注释中，并具有有限的自定义选项。




• 您必须将所有行放在< tbody>< / tbody> 标签中; < thead> 内的行会被忽略。


• 更进一步 - 所有< th> 都会被忽略。要使第一行显眼，请使用< b>< / b> 标签。 单元格格式， align 等将被忽略。


• 您可以指定样式属性中的宽度，并保留下来。
>







示例：





  / ** 
 *演示jsdoc的一个例子，它在jsdoc和googlescript doc中呈现表。否则，毫无意义的胡言乱语。 
 * 
 *< table> 
 *< tbody> 
 *< tr>< td style =width：75％>< b>学生名称< / b>< / td>< td style =width：25％> < b> Idiocy因子< / b>< / td>< / tr> 
 *< tr>< td>约翰史密斯< / 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> 
 * 
 *这里继续介绍函数说明。为什么不能有一个例子？ 
 *< pre> 
 * = myFunc（$ A8，$ DV8）
 *< / pre> 
 * 
 * @param {String}你母亲的名字，例如< code>Anne Murray< / code> 
 * @param {String}出生日期，< code> DD / MM / YYYY< / code> 
 * @returns {Date}预计死亡日期
 * @returns {String}请重试。如果输入错误
 * / 
  

不完美，并且PITA值相当高。不过，jsdoc会确保您获得任何不受支持的标记的语法，对于可移植性来说非常有用。




I know that Issue 1731 has been raised requesting preview of jsdoc within the Google script editor. http://code.google.com/p/google-apps-script-issues/issues/detail?id=1731

While we wait for that to be implemented, what's the best way to preview jsdoc comments that I'm adding to my published library, without requiring me to create a new version?

解决方案

Update 2014: With libraries now supported by the Google Apps Script editor's autocompletion, it's possible to get immediate feedback about SOME of your library's jsdoc comments.

---

This solution isn't ideal - it doesn't provide the same look as published google script libraries - but at least I can work through my jsdoc comments to get a good idea of what they will look like, without constantly creating new versions of my library with no functional enhancements. If someone can detail the additional steps to get the exact output we'd see from publishing, please share!

This is what I've done on a Windows 7 PC. Similar steps may work on other platforms, ymmv.

• Get jsdoc3 by downloading the repository as a zipfile.

• Uncompress into a convenient location. I used C:\jsdoc. This also installs the Rhino jvm that is needed by jsdoc3.

Next, you need to get your google script into a local file that can be parsed by jsdoc3. Again, if anyone knows a better way, I'm all ears!

• Set up a local directory for your google script project. C:\myscript, say.

• Go to your script in google docs / drive / whatever, and copy the whole thing to the system clipboard.

  <ctrl-A> <ctrl-C>
  

• Using your favorite text editor, paste the clipboard contents

  <ctrl-V>
  

• Save the results in a javascript file. C:\myscript\testing.js, say.

Alright, from here it's a matter of parsing the file, auditing the output, and editing your jsdoc comments until you're happy with them.

Output of jsdoc3 will go into an "out" directory.

• Open a command window in C:\myscript.

• Parse your javascript file.

  \jsdoc\jsdoc testing.js
  

• Open the output in your default browser.

  out\index.html
  

• Rinse and repeat, until you have your desired results.

• Copy & paste your edited script back into Google space, validate that your code hasn't broken, and make a new version to generate the documentation for your published library.

Caveats:

• The format of the output is different than you'll see in a published Google Script Libary, but the content is largely the same. Remember that only a subset of jsdoc tags are supported by Google (@param and @returns only) - you can put others in your code, but they will be ignored.

• HTML tables can be included in your jsdoc comments, with limited customization options.

  • You must enclose ALL rows in <tbody></tbody> tags; rows within <thead> get ignored.
  • Further - all <th> get ignored. To make the first row stand out, use <b></b> tags.
  • Don't bother with any cell formatting, align etc. will be ignored.
  • You can specify width within a style attribute, and it survives.

Example:

Here's an example of some elements that render in both jsdoc and 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
 */

Not perfect, and with a fairly high PITA value. Still, jsdoc will make sure you get the syntax of any unsupported tags right, great for portability.

这篇关于如何在Google Doc脚本中预览jsdoc注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！