google-apps-script - 如何在 Google 文档脚本中预览 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 注释来很好地了解它们的外观，而无需不断创建新的我的库的版本没有功能增强。 如果有人可以详细说明获得我们从发布中看到的确切输出的额外步骤，请分享!

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

• 通过将存储库下载为 zipfile 来获取 jsdoc3 .

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

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

• 为您的 Google 脚本项目设置本地目录。 C:\myscript ，说。

• 转到 Google 文档/驱动器/其他位置中的脚本，然后将整个内容复制到系统剪贴板。

  <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 注释中，但自定义选项有限。

  • 您必须将所有行括在 <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 将确保您获得任何不受支持的标签的语法正确，这非常有利于可移植性。