专栏首页Fundebug使用JSDoc自动生成代码文档

使用JSDoc自动生成代码文档

译者按: 代码要有规范的注释,遵从jsDoc规则来注释可以生成有用的文档。

为了保证可读性,本文采用意译而非直译,并且对源代码进行了大量修改。另外,本文版权归原作者所有,翻译仅用于学习。

今天,我来分享如何快速生成JavaScript代码的文档,并且使用Github pages发布。

我首先创建一个示例类JokeMachine,它存储一个笑话列表,调用sayRandomJoke会随机讲一个笑话。

class HelloWorld {

    constructor(){
        this.firstName = '';
        this.lastName = '';
    }

    setName(firstName, lastName){
        this.firstName = firstName;
        this.lastName = lastName;
    }

    getFullName(){
        return this.firstName + ' ' + this.lastName;
    }

    sayHello(){
        console.log('Hello, ' + this.getFullName());
    }
}

添加代码文档

参照jsdoc指导规则,直接在代码中编写文档。

/**
 * HelloWorld类存储一位客人的名字,并打招呼。
 */
class HelloWorld {

    constructor(){
        this.firstName = '';
        this.lastName = '';
    }

    /**
     * 设置客人的姓名
     *
     * @param {String} lastName 姓
     * @param {String} firstName 名
     */
    setName(lastName, firstName){
        this.lastName = lastName;
        this.firstName = firstName;
    }

    /**
     * 获取客人的全名
     *
     * @return {String} 客人的姓名
     */
    getFullName(){
        return this.lastName + ' ' + this.firstName;
    }

    /**
     * 向客人打招呼
     *
     */
    sayHello(){
        console.log('Hello, ' + this.getFullName());
    }
}

使用jsDoc生成文档

现在我们可以为JokeMachine类生成文档。首先,在全局安装jsDoc或则局部安装。我个人喜欢全局安装。

npm install -g jsdoc

如果想知道更多信息,可以参考jsDoc的Github页面

最后,使用如下命令生成文档:

jsdoc Joke.js

你会发现一个名为out的新文件夹。打开文件夹中的index.html,可以看到生成好的文档。

点击右侧导航栏的JokeMachine标签,然后可以查看JokeMachine所有的方法说明。

是不是很酷?

你也许注意到了,没有一个根页面,因为jsDoc根据README.md文件来生成。 因此,我们添加一个。

touch README.md

并简单介绍一下

# 使用jdDoc来生成文档
## Hello World示例
这里是根页面

我们再次生成文档,注意第二个参数是README.md

jsdoc Joke.js README.md

新生成的文档根页面如下:

使用Github pages托管

最简单的方法就是创建一个Github repository, 然后使用免费的Github pages服务(译者注:国内Coding也有相应的服务)。如果你还不知道如何创建repository,可以参考帮助文档

你需要将文件夹重命名为docs,然后去Github网站,到项目的设置(Settings > Github Pages),选择master branch/docs folder, 然后保存。

然后,会生成一个指向该文档的链接:

点击链接,就可以看到文档啦。

版权声明

转载时请注明作者 Fundebug以及本文地址: https://blog.fundebug.com/2017/10/18/generate-docs-with-jsdoc/

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • dotnet 部署 github 的 Action 进行持续集成

    大概只需要 3 分钟就可以在 github 上通过 Action 部署持续集成,本文以 SourceYard 作为例子告诉大家如何配置

    林德熙
  • 开源世界大冒险 | 第 1 期:初识 GitHub

    如果你在 GitHub 上有自己的开源项目或是参与过开源项目,都会成为面试的加分项!

    江不知
  • 前端测试驱动开发模式(TDD)快速入门

    测试驱动开发(Test-Driven Development)是一种软件开发的思维和方法,我的理解是它是一种开发的循环,先写测试代码,再用最小的代码实现这个测试...

    小老鼠
  • 如何创建Maven项目

    顾翔老师开发的bugreport2script开源了,希望大家多提建议。文件在https://github.com/xianggu625/bug2testscr...

    小老鼠
  • gitbook 入门教程之自定义不一样的多语言首页插件

    或者您可以运行 npm install gitbook-plugin-multilingual-index 来本地安装。

    雪之梦技术驿站
  • dotnet 配置 github 自动打包上传 nuget 文件

    在上一篇博客告诉小伙伴如何使用 github 做持续集成,本文告诉大家如何配置 github 让在 master 每次合并都会自动创建一个 nuget 文件,自...

    林德熙
  • VisualStudio 命令行编译 build 通过 rebuild 不通过

    在使用命令行编译项目,发现使用 build 可以编译通过,但是通过 rebuild 编译提示找不到项目,明明在对应的文件夹存在项目输出的 dll 文件,但是会提...

    林德熙
  • gitbook 入门教程之增强版 edit-link-plus 编辑此页插件

    In addition, the supported configuration options are as follows :

    雪之梦技术驿站
  • linux 命令-文本比较comm、diff、patch

    比如,我有两个文件char和chardiff如上,略有不同,就可以用这个命令输出。

    编程三分钟
  • 对featureCounts来源的表达矩阵使用DEXSeq分析可变剪切

    实际上,就一个 -t exon -g gene_name 需要理解一下,就是报名数reads数量的时候,只考虑gtf文件里面记录是exon的坐标的reads,然...

    生信技能树

扫码关注云+社区

领取腾讯云代金券