如何在谷歌文档脚本中预览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 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 Script Libary中看到的格式不同,但内容基本相同.请记住,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将确保您正确获得任何不受支持的标记的语法,非常适合可移植性.