Writing code documentation is one of the most relaxing experiences of my work as a back end developer. When the company I work for, IceMobile, started to develop more and more services in Node.js instead of Java, it also became one of the most challenging bits.

编写代码文档是我作为后端开发人员最轻松的经历之一。 当我工作的公司IceMobile开始使用Node.js而不是Java开发越来越多的服务时，它也成为最具挑战性的领域之一。

I really missed Javadoc in the beginning. Back then, around 2013–14, we already had JSDoc and even though reading the documentation in the source code was alright, rendering in a way that wouldn’t drive my colleagues insane seemed an impossible task. Some annotations were not present at all in the resulting HTML file, others were hanging in the wrong places, and a remarkable amount of workarounds were needed just to get a basic, readable output. Given the amount of freedom one has when implementing code in JavaScript, the JSDoc parser seemed to have trouble identifying annotations within our most… exotic code.

一开始我真的很想念Javadoc。 那时，大约在2013-14年度，我们已经有了JSDoc，尽管可以很好地阅读源代码中的文档，但以一种不会使我的同事发疯的方式进行渲染似乎是不可能的任务。 最终HTML文件中根本没有一些注释，而其他注释则挂在了错误的位置，并且仅为了获得基本的可读输出，就需要大量的解决方法。 考虑到使用JavaScript实现代码时的自由度，JSDoc解析器似乎在识别我们最…… 奇特的代码中的注释时遇到麻烦。

One of these workarounds involved the alleged abuse of the @namespace and @memberOf tags all over the place, which seemed a bit wrong. But after trying to organize the documentation with other tags, it became an accepted evil.

这些变通办法之一涉及@memberOf都是@namespace和@memberOf标记的滥用，这似乎有些错误。 但是，在尝试使用其他标签来组织文档之后，这成为了公认的罪恶。

Some months ago we had to integrate with Contentful, and I was delighted to browse their API documentation. Upon closer inspection, I realized they were also using JSDoc, and they were also heavily depending on those two tags! I was glad to see that other developers in the Node.js community had used the same approach, and I brought some of the learnings from dissecting Contentful’s source code documentation into our repertoire.

几个月前，我们不得不与Contentful集成，我很高兴浏览他们的API文档。 经过仔细检查，我意识到他们也正在使用JSDoc，并且它们在很大程度上还取决于这两个标签！ 我很高兴看到Node.js社区中的其他开发人员也使用了相同的方法，并且我从剖析Contentful的源代码文档中获得了一些经验教训。

Hereby my recommendations.

特此提出我的建议。

使用可读的JSDoc模板 (Use a readable JSDoc template)

No matter how well you document your source code; if you are using a barely legible template, or a template that omits certain annotations, your colleagues or users will have a hard time finding their way around the documentation.

不管您对源代码的记录程度如何； 如果您使用的是难以辨认的模板或省略某些注释的模板，则您的同事或用户将很难在文档中找到自己的方式。

The default JSDoc template is a bit lackluster, and the resulting HTML page is not the most readable. I would suggest using a template like docdash, which provides a clear hierarchical navigation and beautiful syntax highlighting:

默认的JSDoc模板有点乏味，并且生成HTML页面不是最易读的。 我建议使用像docdash这样的模板，该模板可提供清晰的层次结构导航和漂亮的语法突出显示：

The Contentful team has been kind enough to release their own JSDoc template, contentful-sdk-jsdoc, which is both beautiful and readable.

Contentful团队非常友好，可以发布自己的JSDoc模板contentful-sdk-jsdoc ，该模板既美观又可读。

使用名称空间组织文档 (Organize your documentation using namespaces)

This way we can keep our documentation organized. What the abstract concept of a “namespace” means in your project, is up to you to decide. It could be very well tied to your domain model. Given an imaginary Pet Adoption Center SDK written in Node.js, you could have namespaces like Pets, Supporters, Payments, Inventory, etc. Functions and classes belonging to each domain would be documented and annotated with the @memberOf tag to let the JSDoc parser know that the aforementioned entity belongs to a certain namespace.

这样，我们可以使我们的文档井井有条。 “命名空间”的抽象概念在您的项目中意味着什么，取决于您自己决定。 它可能与您的域模型紧密相关。 给定一个假想的用Node.js编写的Pet Adoption Center SDK，您可以拥有Pets ， Supporters ， Payments ， Inventory等命名空间。属于每个域的函数和类都将被记录在案，并使用@memberOf标签进行注释，以使JSDoc解析器知道上述实体属于某个名称空间。

What you can also do is implement a namespace hierarchy with more than one level of depth.

您还可以做的是实现具有多个深度级别的名称空间层次结构。

使用@typedef标记记录复杂的实体。 (Document complex entities using the @typedef tag.)

We can create reusable and complex data model documentation using the @typedef tag. This applies to both function arguments and the data types returned by them.

我们可以使用@typedef标记创建可重用和复杂的数据模型文档。 这适用于函数参数和它们返回的数据类型。

If we define a type like the following…

如果我们定义如下类型：

…then we will be able to reference it everywhere else in our documentation as the type Pets.Pet.

…然后，我们将能够在我们文档的所有其他地方以Pets.Pet类型引用它。

让自己熟悉所有的JSDoc标签！ (Make yourself familiar with all the JSDoc tags!)

Seriously! Read the JSDoc documentation.

认真！ 阅读JSDoc文档 。

I still read the documentation of every single one of the JSDoc tags every now and then, hoping to find some functionality I missed in the previous read.

我仍然时不时地阅读每个JSDoc标记的文档，以期找到我在上一篇文章中缺少的功能。

完整示例，逐步 (Full example, step by step)

Let’s put all these learnings into a practical example. We will set up the documentation of a SDK for an imaginary Pet Adoption Center.

让我们将所有这些学习都变成一个实际的例子。 我们将为一个假想的宠物领养中心建立一个SDK的文档。

在我们的Node.js项目中设置JSDoc (Setting up JSDoc in our Node.js project)

Let’s start by adding the required dependencies:

让我们从添加所需的依赖关系开始：

> npm add --save-dev jsdoc docdash jsdoc-to-markdown

jsdoc being the actual JSDoc module, docdash our template and, for the sake of a more thorough example, we will also be rendering our JSDoc documentation as a Markdown file so that we can easily link it in our project’s README.md. We can achieve this with the module jsdoc-to-markdown.

jsdoc是实际的JSDoc模块， docdash模板做点docdash ，为了更完整的示例，我们还将JSDoc文档呈现为Markdown文件，以便我们可以轻松地将其链接到项目的README.md中。 我们可以使用jsdoc-to-markdown模块来实现。

We will also centralize all the JSDoc configuration into the file jsdoc.json:

我们还将所有JSDoc配置集中到文件jsdoc.json ：

If your SDK exports a complex hierarchy of elements, it’s handy to set the parameter useLongnameInNav to true. This will make sure that namespaces that reflect a “dotted hierarchy” (e.g. sdk.adoptions.dogs) get its name displayed entirely in the resulting HTML page, and not just the last portion of the name (dogs).

如果您的SDK导出了复杂的元素层次结构，将参数useLongnameInNav设置为true很方便。 这将确保反映“点状层次结构”的名称空间(例如sdk.adoptions.dogs )的名称完全显示在结果HTML页面中，而不仅仅是名称的最后一部分( dogs )。

Finally, let’s add a npm script named jsdoc in our manifest to generate the HTML documentation. The resulting package.json file will look something like this:

最后，让我们在清单中添加一个名为jsdoc的npm脚本，以生成HTML文档。 生成的package.json文件将如下所示：

This script assumes that you have a README.md file, that your source code is in the file index.js, that the resulting HTML will be placed in the folder docs/jsdoc, and that the resulting Markdown will be in docs/API.md.

该脚本假设您具有README.md文件，源代码位于文件index.js中，生成HTML将放置在docs/jsdoc文件夹中，并且生成的Markdown将在docs/API.md 。

注释我们的示例宠物领养中心SDK (Annotating our sample Pet Adoption Center SDK)

For convenience’s sake, we will put all our source code in one single file that exports the SDK’s models and their operations. Keep in mind, this is just an example. The idea behind this SDK is that its users can operate it in the following fashion:

为了方便起见，我们将所有源代码放在一个文件中，该文件导出SDK的模型及其操作。 请记住，这只是一个例子。 该SDK的想法是其用户可以按以下方式进行操作：

const sdk = require('pet-store-center-sdk');sdk.pets.register({ name: 'Toby', type: TYPES.DOG, ... });

At this point we haven’t written any types using typedef yet. The resulting file could look something like this:

到目前为止，我们还没有使用typedef编写任何类型。 生成的文件可能如下所示：

We have declared two namespaces, one for Pets and another for Supporters. We have also annotated all the functions with a @memberOf tag, specifying the namespace they to which they belong. Functions have some mandatory and some optional parameters, some of them with default values. To keep it simple, all functions will return a simple “transaction status” object with a transaction identifier and a status boolean. In the next step we will improve our documentation with types.

我们已经声明了两个名称空间，一个用于Pets ，另一个用于Supporters 。 我们还使用@memberOf标记为所有功能添加了@memberOf ，并指定了它们所属的名称空间。 函数具有一些强制性参数和一些可选参数，其中一些具有默认值。 为了简单起见，所有函数都将返回带有事务标识符和状态布尔值的简单“交易状态”对象。 下一步，我们将改进类型的文档。

We will run the task npm run jsdoc to generate the HTML, and we will have a look at it. It should be somewhat similar to this:

我们将运行任务npm run jsdoc来生成HTML，我们将对其进行介绍。 它应该与此类似：

Let’s see what we can improve here!

让我们看看我们可以在这里做些什么！

使用类型和其他有用的标签改进我们的文档 (Improving our documentation with types and other useful tags)

If we look at the documentation generated in the previous step, one can argue that the Returns section of the Pets.adopt item doesn’t really tell us much. It’s an object, sure; but what’s in it? The pet model itself seems to be present in two functions: as the main argument of Pets.register, and also as the property pets in the function Pets.adopt. The property paymentTier in the function Supporters.enroll seems to be some dictionary, but what are the possible values? Let’s make things easier with types!

如果我们看一下在上一步中生成的文档，则可以认为Pets.adopt项的Returns部分并不能真正告诉我们很多信息。 当然，这是一个对象。 但是里面有什么？ 宠物模型本身似乎存在于两个功能：作为Pets.register的主要论点，也可作为财产pets在功能Pets.adopt。 Supporters.enroll函数中的paymentTier属性似乎是一些字典，但是可能的值是什么？ 让我们使用类型使事情变得更轻松！

Our typedef-ed index.js could look something like this:

我们的typedef-ed index.js可能看起来像这样：

• We have added type definitions for the different types of pets (dogs or cats) and breeds. The properties that reflect these data types have been given the appropriate type (e.g. Pets.PetTypes instead of string).

  我们为宠物(狗或猫)和品种的不同类型添加了类型定义。 已经为反映这些数据类型的属性指定了适当的类型(例如， Pets.PetTypes而不是string )。

• Just for fun, we made the function register asynchronous, just to show how we can annotate a function that returns a promise. You can do this by defining the type as Promise<Pets.Pet>.

  只是为了好玩，我们使函数register异步化，只是为了说明我们如何注释返回承诺的函数。 您可以通过将类型定义为Promise<Pets.Pet> 。

• Examples have been added for all the functions.已为所有功能添加了示例。
• Functions that throw an error have been annotated as such. You can go one step further and create your own error type definition.引发错误的函数已如此注释。 您可以再进一步一步，创建自己的错误类型定义。
• Also, we’ve added a type definition for the generic transaction response. This definition has been assigned to a different namespace.另外，我们为通用事务响应添加了类型定义。 此定义已分配给其他名称空间。

• We have replaced @param with @property in the pet model type definition. The @typedef tag will not work so nicely if we use the former.

  在宠物模型类型定义中，我们已将@param替换为@property 。 如果我们使用@typedef标签，它将无法很好地工作。

• That’s a lot of annotations vs. not so much code! True. If it’s too bothersome or it becomes hard to find the right place to put type definitions, you might want to consider moving them into a separate file that only contains such annotations.有很多注释，而不是太多代码！ 真正。 如果太麻烦了，或者很难找到放置类型定义的正确位置，那么您可能要考虑将它们移到仅包含此类注释的单独文件中。

The resulting HTML page for our Pets namespace will now look much fancier!

现在，用于Pets命名空间HTML页面看起来更漂亮了！

结束语和其他有用的标签 (Closing remarks and other useful tags)

那Markdown版本的文档呢？ (What about the Markdown version of the documentation?)

If you remember the npm script jsdoc we created before, we are also generating a Markdown file as part of it. If you commit this file to your GitHub repository, you can link it in the main README.md file. However, it will not look as sexy as the HTML generated by JSDoc.

如果您还记得我们之前创建的npm脚本jsdoc ，我们还将在其中生成Markdown文件。 如果将此文件提交到GitHub存储库，则可以在主README.md文件中将其链接。 但是，它看起来不会像JSDoc生成HTML一样性感。

那班呢？ (What about classes?)

Components like classes or events can also be reliably part of your JSDoc documentation, and are also subject to be incorporated in your namespace hierarchy using the @memberOf tag. Functions that might not be interpreted a functions by the JSDoc parser can be marked so by using the tag @function.

诸如类或事件之类的组件也可以可靠地成为JSDoc文档的一部分，并且还可以使用@memberOf标记并入您的命名空间层次结构中。 可以使用标记@function标记可能不被JSDoc解析器解释为函数的函数。

IDE整合 (IDE integration)

The approach described in this article integrates flawlessly with IDEs like JetBrains’ WebStorm.

本文介绍的方法可以完美地与JetBrains的WebStorm之类的IDE集成。

You will be able to navigate your way to the type definition Pet by command-clicking the word Pet. WebStorm will also recognize that the type of the argument pet in the asynchronous function register is of type Pets.Pet.

通过命令单击“宠物”一词，您将能够导航到类型定义“宠物”。 WebStorm还将认识到异步函数register中的参数pet的类型为Pets.Pet类型。

链接和参考 (Links and references)

You can point your colleagues or users to parts of your documentation using the @see tag. Given the Pet Adoption Center example, should you want to have a link to the documentation of the register function as part of the adopt function, you can do so with @see {Pets.register}.

您可以使用@see标记将同事或用户指向文档的某些部分。 在“宠物领养中心”示例中，如果您希望在adopt功能中包含指向register功能文档的链接，则可以使用@see {Pets.register} 。

External links can be placed pretty much anywhere using the @link tag. Check out the official documentation.

外部链接可以使用@link标记放置在几乎任何地方。 查看官方文档 。

Hopefully this article will help you make your JSDoc documentation more organized and enjoyable.

希望本文能帮助您使JSDoc文档更加井井有条。

Do you have tips or experiences to share about the wonderful world of documenting Node.js projects? Do hit me up!

您是否有技巧或经验可以分享有关记录Node.js项目的精彩世界？ 快打我！