Jsdoc初识与学习准备

微信公众号：lmlweb
一个分享前端技术、面试问题的小小公众号，你的关注都可以让号主开心一整天，嘻嘻;
如果你觉得写的文章对你有帮助，欢迎关注我的简书号和微信公众号^[1]

文章概述

这篇文章介绍jsdoc的概念以及它的应用场景，就是学习它到底香不香，当然香不香还是得看个人，看自己的需求。

内容目录

JSDoc是什么？
Jsdoc的应用场景
Jsdoc应用场景的简单实例
相关学习资料
关注我

JSDoc是什么？

JSDoc是一个根据javascript文件中注释信息，生成JavaScript应用程序或库、模块的API文档 的工具。你可以使用他记录如：命名空间，类，方法，方法参数等。类似JavaDoc和PHPDoc。现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法，并且快速知道如何使用，从而提高开发效率，降低维护成本。

Jsdoc的应用场景

通过上面对Jsdoc的介绍就可以大概看出它的应用场景了，如下，是我自己简单的归纳

1. 生成开发js或ts（尤其是）项目的接口文档
2. 通过Jsdoc优化你的前端编辑器的代码提示功能

Jsdoc应用场景的简单实例

1. 使用Jsdoc生成接口文档

   写一个demo，如下：

   /***Book类，代表一个书本.
   *@constructor
   *@param {string} title - 书本的标题.
   *@param {string} author - 书本的作者.**/
   function Book(title, author) {
    this.title=title;
    this.author=author;
   }
    Book.prototype={
    /** 
     * 获取书本的标题 
     * @returns {string|*} 
     */
   getTitle:function(){ 
     return this.title;
    },
   /** 
   * 设置书本的页数 
   * @param pageNum {number} 页数 */
   setPageNum:function(pageNum){   
      this.pageNum=pageNum;
     }
   };
   

   使用Jsdoc工具生成的接口文档如下：

   text

   <figcaption style="line-height: inherit; margin: 0px; padding: 0px; margin-top: 10px; text-align: center; color: rgb(153, 153, 153); font-size: 0.7em;">text</figcaption>

2.vscode配合Jsoc优化代码提示

Jsdoc注释代码

export class CommonUtilsWX {    
 /**    
  * 发送网络请求，通信协议必须是http或https，数据协议必须是json     
  * @param {object} o 请求参数对象     
  * @param {string} o.host 请求url的域名，如http://xxx.xxx.com     
  * @param {string} o.path 请求url的路径，如xxx/xxx     
  * @param {object} o.query 请求url的查询段，根据对象中key，value拼成key1=value1&key2=value2的形式     
  * @param {string} o.method 请求方法，如GET，POST等    
 * @param {object} o.body 请求数据体，仅在method为POST时有效  
 * @param {function(Error):void} callback 请求回调，请求成功时error为空     */   
  request(o, callback){        //TODO:xxxxx    }}

实现效果

text

相关学习资料

关于文档中文手册可以自己去找，这里分享两篇Jsdoc入门使用文章

1. https://www.jianshu.com/p/161495917279
2. https://www.jianshu.com/p/b86cc11112bd

下一篇文章会介绍vscdoe如何配置智能提示，感兴趣的小伙伴可以点个关注。

关注我

如果你觉得这篇文章对你有帮助的话，不妨小小关注或者是点赞一下，你的关注是我继续写文章的巨大动力，阿里嘎多！