在 JavaScript 中是否有指定作者、日期或代码来源的约定？

Question

我想指定外部函数的来源（例如来自 Whosebug 的此处）。另外，我想将我的姓名、日期和网站添加到我自己的功能中。

我当然可以按照我想要的方式将所有内容放在评论中。但是我应该遵循某些约定吗？甚至机器可读？

Answer 1

JSDoc通常用于为javascript代码指定元数据，可用于自动生成文档。参见：https://jsdoc.app/about-getting-started.html

示例：

/**
 * @author Some Guy <example@example.com>
 * @see {@link https://jsdoc.app/tags-description.html} for further information.
 * @description How to use JSDoc to tag javascript.
 */

Answer 2

没有官方方式来指定它。至少没有一个真正的方法。

话虽如此，最广为接受的是JSDoc comments. You need to start a block comment with /** (two asterisks) and then you can use the special JSDoc syntax to explain your source with @author and @see:

/**
 * Function that returns a random number
 * @author Jon Skeet
 * @see {@link 
 * 
 * @param {number} min - minimum bound (inclusive)
 * @param {number} max - maximum bound (inclusive)
 * @return {string} - uniformly distributed integer within the range as a string 
 */
function rand(min, max){
   return (Math.floor(Math.random() * (max - min + 1)) + min).toFixed(0);
}

Maybe even machine readable?

JSDoc 是机器可读的。有许多使用它的工具。最值得注意的是，许多标准 JavaScript 编辑器，如 Visual Studio Code 将为您提供悬停功能的 JSDoc。

但是，还有其他工具可以使用 JSDoc 或其子集。他们可能会根据为 @param and @return 或其他任务指定的内容生成文档或执行类型检查。

还值得注意的是，您不需要任何工具即可使用 JSDoc。您可以直接在源代码中编写它，即使它从未被使用过。它仍然可以被其他理解它的人阅读。即使是第一次接触文档风格，也足够简单易懂。

在 JavaScript 中是否有指定作者、日期或代码来源的约定？

Is there a convention for specifying the author, date, or source of code in JavaScript?

javascript

reference

comments

resourcereference