如何在 google doc 脚本中预览 jsdoc 注释

Question

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

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

Answer 1

2014 年更新：Google Apps 脚本编辑器的自动完成功能现在支持库，因此可以立即获得有关您库的某些 jsdoc cmets 的反馈。

---

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

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

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

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

接下来，您需要将您的 google 脚本放入可以被 jsdoc3 解析的本地文件中。 再一次，如果有人知道更好的方法，我会全力以赴！

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

• 转到您在 google docs/drive/whatever 中的脚本，然后将整个内容复制到系统剪贴板。

  <ctrl-A> <ctrl-C>
  

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

  <ctrl-V>
  

• 将结果保存在 javascript 文件中。 C:\myscript\testing.js，比如说。

好的，从这里开始解析文件、审核输出并编辑您的 jsdoc cmets，直到您对它们满意为止。

jsdoc3 的输出将进入“out”目录。

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

• 解析您的 javascript 文件。

  \jsdoc\jsdoc testing.js
  

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

  out\index.html
  

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

• 将您编辑的脚本复制并粘贴回 Google 空间，验证您的代码没有损坏，然后制作一个新版本来为您发布的库生成文档。

注意事项：

• 输出的格式与您在已发布的 Google 脚本库中看到的不同，但内容大致相同。请记住，Google 仅支持 jsdoc 标记的子集（仅限 @param 和 @returns）——您可以将其他标记放入您的代码中，但它们将被忽略。

• HTML 表格可以包含在您的 jsdoc cmets 中，但自定义选项有限。

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