7

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

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

4

1 回答 1

6

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

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

这就是我在 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 注释，直到您对它们满意为止。

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

于 2012-09-20T15:42:20.250 回答