如何预览谷歌文档脚本中的jsdoc注释

Question

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

在我们等待实现的同时，在不需要创建新版本的情况下，预览我添加到已发布库中的jsdoc注释的最佳方式是什么？

Answer 1

2014年更新：Google Apps脚本编辑器的自动完成现在支持库，可以立即获得有关库的一些jsdoc评论的反馈。

---

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

这是我在Windows7 PC上所做的。类似的步骤可能在其他平台上也适用，ymmv。

• 通过将存储库下载为zip文件来获取jsdoc3。

• 解压缩到方便的位置。我使用了C:jsdoc。这还安装了jsdoc3所需的Rhino jvm。

接下来，您需要将您的谷歌脚本放入一个可以由jsdoc3解析的本地文件中再说一遍，如果有人知道更好的方法，我洗耳恭听

• 为您的谷歌脚本项目设置一个本地目录。比如C:myscript。

• 转到谷歌文档/驱动器/任何东西中的脚本，并将整个内容复制到系统剪贴板。

  <ctrl-A> <ctrl-C>
  

• 使用您喜欢的文本编辑器，粘贴剪贴板内容

  <ctrl-V>
  

• 将结果保存在javascript文件中。比如C:myscripttesting.js。

好吧，从这里开始，就是解析文件、审核输出和编辑jsdoc注释，直到您对它们感到满意。

jsdoc3的输出将进入一个"out"目录。

• 在C:myscript中打开命令窗口。

• 分析您的javascript文件。

  jsdocjsdoc testing.js
  

• 在默认浏览器中打开输出。

  outindex.html
  

• 冲洗并重复，直到你得到你想要的结果。

• 复制&将编辑后的脚本粘贴回Google空间，验证代码是否已损坏，并制作一个新版本以生成已发布库的文档。

注意事项：

• 输出的格式与您在已发布的谷歌脚本库中看到的不同，但内容基本相同。请记住，谷歌只支持jsdoc标记的一个子集(仅@param和@return)-您可以将其他标记放在代码中，但它们将被忽略。

• HTML表可以包含在jsdoc注释中，但自定义选项有限。

  • 必须将所有行包含在<tbody></tbody>标记中；<thead>中的行将被忽略
  • 此外，所有<th>都将被忽略。要使第一行突出，请使用<b></b>标记
  • 不要为任何单元格格式而烦恼，align等将被忽略
  • 您可以在样式属性中指定宽度，并且它仍然存在

示例：

以下是在jsdoc和googlescript文档中呈现的一些元素的示例：

/**
* 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会确保您正确使用任何不支持的标记的语法，这对可移植性来说非常好。