如何为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作用域相关的特定于@tags和仅在那里记录的附加组件。