使用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/
使用JSDoc自动生成代码文档的更多相关文章
- 用doxygen+graphviz自动化生成代码文档(附详细教程)
一.引子 用这两个工具可以自动的遍历代码,并且产生代码文档,我们先来看看效果,然后放出这两个工具的下载地址. 二.工具的下载地址 doxygen:http://www.stack.nl/~dimitr ...
- golang学习之生成代码文档
go doc 工具会从 Go 程序和包文件中提取顶级声明的首行注释以及每个对象的相关注释,并生成相关文档. 一般用法: go doc package 获取包的文档注释,例如:go doc fmt 会显 ...
- 【转】windows环境下利用doxygen生成代码文档
作者:jiangwenna http://www.jiangwenna.com/windows-doxygen-doc/ Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统 ...
- 【转载】doxygen+graphviz生成代码文档
一.工具 doxygen:http://www.stack.nl/~dimitri/doxygen/download.html graphviz:http://www.graphviz.org/ 二. ...
- 代码文档生成工具-Doxygen生成CHM和RTF图文教程
Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,可以从一套归档源文件开始,生成chm格式的文档.本文主要讲解如何在winddows下安装doxygen. 1.下载do ...
- 使用SHFB(Sandcastle Help File Builder)建立MSDN风格的代码文档
使用SHFB(Sandcastle Help File Builder)建立MSDN风格的代码文档 下载地址:http://sandcastle.codeplex.com/ 下载地址2:http:// ...
- 使用doxygen制作C代码文档
使用doxygen制作C代码文档 C 代码注释风格约定 行间注释 /*! * * 这里是注释 * */ 行内注释 <code here> /*! 这里是注释 */ doxygen 风格的宏 ...
- doxygen 生成源码文档
使用doxygen 生成源代码的文档是相当方便的,本文就简单整理下doxygen的使用说明 1. 安装 关于安装的问题不做特殊的说明,这里直接使用命令安装, 源码安装不做介绍 ubuntu: sudo ...
- appledoc导出iOS代码文档的使用和问题详解(干货篇)
appledoc导出iOS代码文档的使用和问题详解(干货篇) 1. 简单说一下背景和自己感受 背景: 项目好像突然黄了,公司让详细写项目代码的注释并且导出文档,弄完之后就要封版. 说实话:听到这个消息 ...
随机推荐
- Windows 10 IoT Core 17101 for Insider 版本更新
除夕夜,微软发布了Windows 10 IoT Core 17101 for Insider 版本更新,本次更新只修正了一些Bug,没有发布新的特性. 已知的问题: F5 driver deploym ...
- CTF中文件包含的一些技巧
i春秋作家:lem0n 原文来自:浅谈内存取证 0x00 前言 网络攻击内存化和网络犯罪隐遁化,使部分关键数字证据只存在于物理内存或暂存于页面交换文件中,这使得传统的基于文件系统的计算机取证不能有效应 ...
- Javascript高级编程学习笔记(76)—— 表单(4)选择文本
文本框脚本 在HTML中文本框有两种实现方式: <input> <textarea> 这两种实现方式虽然在多数情况下表现一致,但是两者之间仍存在许多重要区别 对于<inp ...
- Java初学者最佳的学习方法以及会遇到的坑(内含学习资料)!
最近系统整理了一套java初学者最佳的学习方法以及会遇到的坑等,希望对你有所帮助. 目录: 一.学习java的前提 二.学习java的方法 三.学习java时的坑 四.学习java的路线(画重点) 一 ...
- 【翻译】Neural Collaborative Filtering--神经协同过滤
[说明] 本文翻译自新加坡国立大学何向南博士 et al.发布在<World Wide Web>(2017)上的一篇论文<Neural Collaborative Filtering ...
- Git:fatal: Authentication failed
1.删除保存的用户名和密码 执行 下面的命令,删除保存的用户名和密码 git config --system --unset credential.helper 重新操作,提示输入用户名和密码,操作成 ...
- JavaScript 快速入门
JavaScript是jquery的基础, JavaScript是一种描述性语言 JavaScript的组成 :ECMAScript,BOM,DOM. JavaScript的基本结构 <scri ...
- ubuntu 16.04 安装matlab的替代工具Octave及使用指南
为什么要安装Octave? 它是什么? GNU Octave是自由软件基金会(Free Software Foundation)支持的遵循GPL协议(GNU General Public Licens ...
- Ubuntu安装Python2.7,nodejs,Redis
安装Python2.7 sudo add-apt-repository ppa:fkrull/deadsnakes-python2.7sudo apt-get update sudo apt-get ...
- Abp + MongoDb 改造默认的审计日志存储位置
一.背景 在实际项目的开发当中,使用 Abp Zero 自带的审计日志功能写入效率比较低.其次审计日志数据量中后期十分庞大,不适合与业务数据存放在一起.所以我们可以重新实现 Abp 的 IAuditi ...