译者按: 代码要有规范的注释,遵从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自动生成代码文档的更多相关文章

  1. 用doxygen+graphviz自动化生成代码文档(附详细教程)

    一.引子 用这两个工具可以自动的遍历代码,并且产生代码文档,我们先来看看效果,然后放出这两个工具的下载地址. 二.工具的下载地址 doxygen:http://www.stack.nl/~dimitr ...

  2. golang学习之生成代码文档

    go doc 工具会从 Go 程序和包文件中提取顶级声明的首行注释以及每个对象的相关注释,并生成相关文档. 一般用法: go doc package 获取包的文档注释,例如:go doc fmt 会显 ...

  3. 【转】windows环境下利用doxygen生成代码文档

    作者:jiangwenna    http://www.jiangwenna.com/windows-doxygen-doc/ Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统 ...

  4. 【转载】doxygen+graphviz生成代码文档

    一.工具 doxygen:http://www.stack.nl/~dimitri/doxygen/download.html graphviz:http://www.graphviz.org/ 二. ...

  5. 代码文档生成工具-Doxygen生成CHM和RTF图文教程

    Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,可以从一套归档源文件开始,生成chm格式的文档.本文主要讲解如何在winddows下安装doxygen.     1.下载do ...

  6. 使用SHFB(Sandcastle Help File Builder)建立MSDN风格的代码文档

    使用SHFB(Sandcastle Help File Builder)建立MSDN风格的代码文档 下载地址:http://sandcastle.codeplex.com/ 下载地址2:http:// ...

  7. 使用doxygen制作C代码文档

    使用doxygen制作C代码文档 C 代码注释风格约定 行间注释 /*! * * 这里是注释 * */ 行内注释 <code here> /*! 这里是注释 */ doxygen 风格的宏 ...

  8. doxygen 生成源码文档

    使用doxygen 生成源代码的文档是相当方便的,本文就简单整理下doxygen的使用说明 1. 安装 关于安装的问题不做特殊的说明,这里直接使用命令安装, 源码安装不做介绍 ubuntu: sudo ...

  9. appledoc导出iOS代码文档的使用和问题详解(干货篇)

    appledoc导出iOS代码文档的使用和问题详解(干货篇) 1. 简单说一下背景和自己感受 背景: 项目好像突然黄了,公司让详细写项目代码的注释并且导出文档,弄完之后就要封版. 说实话:听到这个消息 ...

随机推荐

  1. Windows 10 IoT Core 17101 for Insider 版本更新

    除夕夜,微软发布了Windows 10 IoT Core 17101 for Insider 版本更新,本次更新只修正了一些Bug,没有发布新的特性. 已知的问题: F5 driver deploym ...

  2. CTF中文件包含的一些技巧

    i春秋作家:lem0n 原文来自:浅谈内存取证 0x00 前言 网络攻击内存化和网络犯罪隐遁化,使部分关键数字证据只存在于物理内存或暂存于页面交换文件中,这使得传统的基于文件系统的计算机取证不能有效应 ...

  3. Javascript高级编程学习笔记(76)—— 表单(4)选择文本

    文本框脚本 在HTML中文本框有两种实现方式: <input> <textarea> 这两种实现方式虽然在多数情况下表现一致,但是两者之间仍存在许多重要区别 对于<inp ...

  4. Java初学者最佳的学习方法以及会遇到的坑(内含学习资料)!

    最近系统整理了一套java初学者最佳的学习方法以及会遇到的坑等,希望对你有所帮助. 目录: 一.学习java的前提 二.学习java的方法 三.学习java时的坑 四.学习java的路线(画重点) 一 ...

  5. 【翻译】Neural Collaborative Filtering--神经协同过滤

    [说明] 本文翻译自新加坡国立大学何向南博士 et al.发布在<World Wide Web>(2017)上的一篇论文<Neural Collaborative Filtering ...

  6. Git:fatal: Authentication failed

    1.删除保存的用户名和密码 执行 下面的命令,删除保存的用户名和密码 git config --system --unset credential.helper 重新操作,提示输入用户名和密码,操作成 ...

  7. JavaScript 快速入门

    JavaScript是jquery的基础, JavaScript是一种描述性语言 JavaScript的组成 :ECMAScript,BOM,DOM. JavaScript的基本结构 <scri ...

  8. ubuntu 16.04 安装matlab的替代工具Octave及使用指南

    为什么要安装Octave? 它是什么? GNU Octave是自由软件基金会(Free Software Foundation)支持的遵循GPL协议(GNU General Public Licens ...

  9. Ubuntu安装Python2.7,nodejs,Redis

    安装Python2.7 sudo add-apt-repository ppa:fkrull/deadsnakes-python2.7sudo apt-get update sudo apt-get ...

  10. Abp + MongoDb 改造默认的审计日志存储位置

    一.背景 在实际项目的开发当中,使用 Abp Zero 自带的审计日志功能写入效率比较低.其次审计日志数据量中后期十分庞大,不适合与业务数据存放在一起.所以我们可以重新实现 Abp 的 IAuditi ...