使用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

Fundebug专注于JavaScript、微信小程序、微信小游戏、支付宝小程序、React Native、Node.js和Java线上应用实时BUG监控。 自从2016年双十一正式上线,Fundebug累计处理了9亿+错误事件,付费客户有Google、360、金山软件、百姓网等众多品牌企业。欢迎大家免费试用

版权声明

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

您的用户遇到BUG了吗?

体验Demo 免费使用