betway必威-betway必威官方网站
做最好的网站

js下的部署,进阶系列

原稿地址:

简单说,用JSDoc写开拓文档正是写注释,只是在书写的时候要把它们遵照标准工整的写出来,那样就可以达到注释的目标又能顺便地让JSDoc生成规范的文书档案,一石二鸟。那样想专门的学业就大概多了不是啊?

阅读目录

官网

  • ESDoc:
  • JSDoc:

怎么做?

自身那边只讲在node.js平台下的操作步骤。

  • 一、WebApiTestClient介绍
  • 二、WebApiTestClient展示
  • 三、WebApiTestClient使用
    • 一、怎么着引进组件
    • 二、怎样使用组件
  • 四、总结

介绍

ESDoc 是三个依照 javascript 文件中注释消息,生成 JavaScript 应用程序或库、模块的 API 文书档案的工具。具备文书档案覆盖率总计、系统手册、1体化测试、详细接口表达等性格。

全局安装JSDoc注重包:
npm i jsdoc -g

 

ESDoc 与 JSDoc 对比

JSDoc 是眼前最火的文书档案生成工具,它存在的时刻也相比较长,然而意义上还相差不离,比方文档覆盖率、自动测试、搜索等,都不曾落到实处。并且它的运用相比较复杂,要求从严使用标签,过多正视备注来实现。它最大的坑是同名接口不能够区分。

  ESDoc JSDoc
ES标准 ES6 以上 ES6
模块化 Class、import & export Class、import & export、CommonJS、AMD、Prototype
注释类型 块级注释 块级注释
标签 少量标签 标签完善,需要严格使用
文档内容 自动语义化,说明详细 注释中提炼
覆盖率 支持
测试 支持
手册 支持多个文档 支持多个文档
搜索 支持
插件 支持 支持
同名接口 重叠显示 分开显示
不管写四个包罗JSDoc注释的js文件呢:
    /** 
     * JSDoc Demo File
     * see more link to <a href="http://blog.pagegaga.com">blog.pagegaga.com</a>
     * @author Warren <aliang_ok@sina.com>
     * @copyright Warren 2016
     */

    /** 
     * Say hello.
     * @param {string} str - Anything what you want to say.
     */
    var app=function(str){
        alert('hello');
    }

正文

示例


点击左上角 Try it out

接下来就能够在档案的次序根目录下实行命令,对要转移文书档案的文件做剖析了:
jsdoc ./

上面这段命令是说对品种根目录(不包含子目录)下有所文件做深入分析,那样做的结果是JSDoc分析钦定目录全数包涵以JSDoc标准书写注释的文本,并在私下认可目录(./out)下生成可供浏览器访问的html文件及有关依赖(包含样式、字体、脚本等)文件。实践到位后,就足以在项目根目录里找到./out/index.html文件双击预览了。

前言:那两日在整WebApi的劳务,由于调用方是Android客户端,Android开拓人士也不懂C#语法,API里面包车型客车接口也不能够向来给她们看,不能,只有1切详细一点的文书档案呗。由于接口个数有一些多,每种接口都要详细表明接口效用、参数类型、重回值类型等等,写着写着把博主惹毛了,难道这种文书档案非要本人写不成?难道网络未有这种文档的来得工具吗?带着那多个难点,在互联网世界里找找,网络世界很蹊跷,只要你用心,总能找到或多或少的协理!那不就被博主找到了那些好用的组件:WebApiTestClient。它对于接口的功力、参数功用以及项目、再次回到值表明等等都能很好表现,并且提供测试调用的效果,输入测试参数发送请求,就会获得相应的回到结果。哇塞,这一层层可视化的效应不即是博主需求的啊,还写什么文档,赶紧用起来!

Home

读取根目录 README.md 文件,能够用来记录项目为主新闻。

JSDoc 提供了数不尽命令行参数,能够看法定文书档案关于命令行相关的验证,这里大约举个例证:

大家得以奉行npm i docdash --save-dev设置1个第一方的宗旨包,然后实施如下命令:

jsdoc ./app.js -d ./doc -t ./node_modules/docdash

结果是,JSDoc把app.js中的注释生成文书档案并放置了钦点目录(./doc)下,同时生成的文书档案套用了docdash主旨。

 

Manual

读取本地配置的 markdown 文件,能够用于记录项目相关资料。

在指令行里试行命令每趟都要重写叁次这个大块文章的布局参数很勤奋,不怕,JSDoc可以引用外部配置文件让职业一劳永逸:

在品种目录下新建贰个名称叫jsdoc.cfg.json的布局文件,然后以JSON格式填写如下内容到那些布局文件中:

    {
        "source":{
            "include":[".","./server/"],
            "exclude":["./node_modules/"]

        },
        "opts":{
            "template":"node_modules/docdash",
            "encoding":"utf8",
            "destination":"./jsdoc/",
            "readme":"readme.md"
        }
    }

有关那一个安插项的解说,能够在官网找到。保存后,再实行如下命令:

jsdoc -c jsdoc.cfg.json

诸如此类,JSDoc就能够依照钦赐的安插文件中的配置新闻来管理文档了。

打听通晓怎么调换文书档案,剩下的主题素材便是怎么写规范的注明技术生成像样的开销毁文件书档案了。

回到顶端

Reference

接口的详实表达,依照注释自动生产。

怎么写?

JSDoc注释以/**开头*/最后,并且每1行起先都有八个*。在讲明段内经过以@开始的价签为代码提供注解,JSDoc依照那些标签来公司文书档案结构,套用样式最后生成文书档案。大家在此地只举多少个常用的例子:

一、WebApiTestClient介绍

一、WebApiTestClient组件功效首要有以下多少个:

(一)、将WebApi的接口放到了浏览器里面,以可视化的点子展现出来,举例我们经过

(二)、能够详细查看API的类表达、方法求证、参数表达、再次来到值表明。只须要我们在定义方法时候加多 /// <summary> 这种详细申明就可以,组件自动读取注释里面包车型客车剧情显示在分界面下边。

(三)、能够修改http请求头文件Head和呼吁体Body里面包车型大巴参数,内定发送http请求的性状,举个例子内定我们最常见的contentType提醒参数的种类。

(肆)、组件具备测试接口的意义,用过Soup UI的情侣应该清楚,通过Soup UI能够方便测试WebService参数以及再次回到值。大家的WebApiTestClient也得以兑现类似的机能,直接通过页面上的测试按键,就会测试接口。

二、WebApiTestClient是贰个开源组件。开源地址:

回到顶端

Source

接口的源代码,同时提供文档覆盖率查看。

种种模块都可以有那般的价签:
    /** 
     * description
     * description more
     * @author author name <email>
     * @copyright copyright information
     */
  • description 用来叙述代码段,个中能够插入html成分,比方2个a链接,
  • @author能够申明该代码块的小编,
  • @copyright用来声称版权。

二、WebApiTestClient展示

第二印象:接口列表。 图片 1

点击某1个接口查看接口详细。举例本文查看Get请求的无参方法,右下角有按键能够测试接口。

图片 2

点击“Test API”按钮

图片 3

点击Send发送请求

图片 4

第三个有参数的接口

图片 5

手动输入参数,得到再次回到结果

假若参数的项目是指标,能够直接剖判class定义方面的 /// <summary> 标注,呈现如下

图片 6

出于是post请求,固然急需实行参数长度和花色,能够通过content-length和content-type来钦赐。并且切实可行的参数可以钦定分化格式展现,举例下图的application/json和application/xml

取得重回值

归来顶端

Test

接口的测试,首要用于纯 JS 代码。

function:
    /** function description
     * @param {type} paramName - description
     * @returns {type} description
     */
  • @param 用来描述函数参数,{type}是1个内联标签,用来注脚该参数的品类(比方string、object、number),-前面再写该参数的叙述文字;
  • @returns用来标注该函数最终回到什么品种的值并加以注脚。

三、WebApiTestClient使用

回去顶上部分

本文由betway必威发布于网页设计,转载请注明出处:js下的部署,进阶系列

Ctrl+D 将本页面保存为书签,全面了解最新资讯,方便快捷。