stefanzan分享 http://blog.sciencenet.cn/u/stefanzan

博文

使用JSDoc自动生成代码文档

已有 1890 次阅读 2017-10-19 20:33 |个人分类:debug|系统分类:博客资讯

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

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

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

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

classHelloWorld{
constructor(){
this.firstName = '';
this.lastName = '';
   }
   setName(firstName, lastName){
this.firstName = firstName;
this.lastName = lastName;
   }
   getFullName(){
returnthis.firstName + ' ' + this.lastName;
   }
   sayHello(){
console.log('Hello, ' + this.getFullName());
   }
}

添加代码文档

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

/**
* HelloWorld类存储一位客人的名字,并打招呼。
*/
classHelloWorld{
constructor(){
this.firstName = '';
this.lastName = '';
   }
/**
    * 设置客人的姓名
    *
    * @param {String} lastName 姓
    * @param {String} firstName 名
    */
   setName(lastName, firstName){
this.lastName = lastName;
this.firstName = firstName;
   }
/**
    * 获取客人的全名
    *
    * @return {String} 客人的姓名
    */
   getFullName(){
returnthis.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, 然后保存。



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



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













https://blog.sciencenet.cn/blog-811611-1081609.html

上一篇:Async/Await是这样简化JavaScript代码的
下一篇:我为什么推荐Prettier来统一代码风格
收藏 IP: 58.23.11.*| 热度|

0

该博文允许注册用户评论 请点击登录 评论 (0 个评论)

数据加载中...
扫一扫,分享此博文

Archiver|手机版|科学网 ( 京ICP备07017567号-12 )

GMT+8, 2024-4-20 01:10

Powered by ScienceNet.cn

Copyright © 2007- 中国科学报社

返回顶部