如何为 Google Apps 脚本编写正确的文档？

Question

我是一名正在学习编码的营销人员。目前我选择的主要武器是 Google Apps Scripts。当我深入研究并为其他人编写代码时，我想确保我的代码有很好的文档记录。在 GAS 之前，我从 Python 开始，其中 PEP-8 对此有明确的指导方针。GAS 有类似的指南吗？

我当前如何记录函数（除了具有清晰的变量名称和一些内联注释之外：

在每个脚本的顶部：

/**
 * @name The name of the script
 *
 * @fileoverview The overview and expected outcome 
 *
 * @author my name and e-mail address
 *
 * @version 1.0
 *
 * @changelog
 * - version 1.0
 *   - Released initial version.
 */

每个函数定义如下：

function buildResultsObject(contactList) {
  /**
   * Parses the contactList to create
   * an object per countryCategory ID
   *
   * The data array in the object is initialised
   * to be empty and will be filled when the 
   * data is parsed with another function.
   *
   * @param {contactList} the values from the contact list sheet as a 2-level array
   * @returns {Object} results
   *
   * Example structure of results:
   * 
   *  {'AUBAK':
   *    {
   *    'country; 'AU'
   *    'category': 'BAK'
   *    'email': 'a@b.com',
   *    'data': []
   *    }
   *  }
   *
   */

  code here
}

我的问题：

• 这是我应该这样做还是有更好的方法？
• 评论中的@标签到底有什么作用？例如，我注意到使用 @name 参数，我实际上正在更改可以在菜单栏下方的“选择函数”下拉列表中运行的脚本的名称。

Answer 1

以下链接应该足够了：

https://google.github.io/styleguide/jsguide.html

上面链接的指南中的第 7 章涵盖了您需要了解的所有内容。

但您还应该查看应用程序脚本参考文档（和附加组件文档），因为有一些与 oauth 范围和附加组件相关的 GAS 特定 @tags 仅记录在那里。