Document generation technology selection

1. Technology selection and comparison of alternative schemes

alternative jsdoc vuepress
website There is no [vuepress website] (

www.vuepress.cn/guide/using… )
github jsdoc gitHub Vuepress related websites
Help document Jsdoc Chinese language documentation Vuepress Chinese website
advantages Automatically generate documents, support topic switching, according to the project generation Nice interface, code isolation, component references
disadvantages Based on project generation Manual maintenance required
The sample Tencent IM Document,Eggjs document Vue official related projects

　

2. Quick use of JSDoc

JSDOC is an API document generator that generates HTML documents for you from comments that you simply add to your code in a specific format.

2.1 Global Installation:

// NPM install -g jsdocCopy the code

If you prefer in-project use, you can also choose:

2. 2 Basic Usage

Using JSDOC is very simple: write comments for JavaScript files and use JSDOC to parse them:

2.2.1 new demo. Js

// demo.js

/** * function: format the timestamp as a string * in the specified format@param {Number} milliSec- The time to convert, which can be second, millisecond, microsecond, or Date *@param {String} [formatStr] - Target format String Optional Default: 'YYYY-MM-DD hh: MM :ss' *@returns {String} - Converts a time value (or Date) to a time string */ based on the target time format
function formatTime(milliSec, formatStr = DEFAULT_FORMAT_STR) {
  // code
}
Copy the code

2.2.2 Generating documents by Running Commands

jsdoc demo.js
Copy the code

2.2.3 Effect display

3 Used in projects to generate documents through configuration items

Add jsdoc.json to the project root directory and specify it with the -c argument:

// jsdoc.json

{
  "source": {
    "include": [ "src/"]."exclude": [ "src/libs"]},"opts": {
    "template": "node_modules/docdash"."encoding": "utf8"."destination": "./docs/"."recurse": true."verbose": true}}Copy the code
jsdoc -c jsdoc.json
Copy the code

Whether JSDOC is installed globally or locally, it is recommended to invoke it using NPM scripts, that is, to add the command to the scripts of package.json (called build:doc here, you can call it anything you like) :

{
  "scripts": {
    "build-doc": "jsdoc -c jsdoc.json"}}Copy the code

This way we can generate documentation by NPM run build-doc.

If you can automatically generate documents after modifying files, you only need to use a tool like Nodemon to listen for changes of specified files and then automatically execute NPM run build-doc.

4. Jsdoc, add VUE support

4.1 JSDoc does not support JS files by defaultJsdoc plug-in

npm install --save-dev jsdoc jsdoc-vuejs
Copy the code

4.2 Adding a VUE File

<template>
  <div>Hello world!</div>
</template>

<script>
  / * * *@vue-prop {Number} initialCounter - Initial counter's value
   * @vue-prop {Number} [step=1] - Step
   * @vue-data {Number} counter - Current counter's value
   * @vue-computed {String | Number} message
   * @vue-event {Number} increment - Emit counter's value after increment
   * @vue-event {Number} decrement - Emit counter's value after decrement
   * @module Quotation management - module - Actively push orders */
  export default {
    props: {
      initialCounter: {
        type: Number.required: true,},step: {
        type: Number.default: 1,
      },
    },
    data () {
      return {
        counter: 0,}},computed: {
      message() {
        return `Current value is The ${this.counter}`; }},methods: {
      increment() {
        this.counter += 1;
        this.$emit('increment'.this.counter);
      },
      decrement() {
        this.counter -= 1;
        this.$emit('decrement'.this.counter); }}}</script>
Copy the code

4.3 Modifying Configuration Items: Added the jSdoc-vuejs configuration item

{
  "plugins": [
    "node_modules/jsdoc-vuejs"
  ],
  "source": {
    "include": [ "src/" ],
    "includePattern": "\\.(vue|js)$",
    "exclude": [ "src/libs" ]
  },
  "opts": {
    "template": "templates/default",
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true,
    "verbose": true
  }
}
Copy the code

5. Configuration file Description (Jump gate)

JSDOC has many configuration items, the most commonly used are the following:

  • sourceRepresents the file passed to JSDOC
  • source.includeIndicates which files JSDOC needs to scan
  • source.excludeIndicates which files JSDOC needs to exclude
  • optsRepresents the option passed to JSDOC
  • opts.templateA template for generating documents, the default istemplates/default
  • opts.encodingRead the encoding of the file, default isutf8
  • opts.destinationThe path to the generated document, the default is./out/
  • opts.recurseWhether the runtime recurses to subdirectories
  • opts.verboseWhether to output details at runtime. The default is yesfalse

6. NotesJump gate

As we know, JSDOC works by analyzing comments in JavaScript files to generate HTML documents. However, if we want JSDOC to produce the right results, we need to write the comments in the right format. It accepts comments in the following format:

This is the level block comment we see in JavaScript. Note that the JSDOC parser requires that comments begin with /**, and comments that begin with /*, /***, or more than three asterisks are ignored.

With this level of block annotation, we can document as needed inside. JSDOC provides us with a very rich set of tags that its parser does extra processing on. These labels can be roughly divided into two categories: level block labels and inline labels.

  • Level block label: located at the top of the comment. Most tags in JSDOC are level block tags.
  • Inline tags: A label within a block label, such as@link,@tutorial.

Here are some common block tags:

  • @authorThe author of the class/method.
  • @classIndicates that this is a class.
  • @function/@methodIndicates that this is a function/method (this is a synonym).
  • @privateIndicates that the class/method is private and JSDOC does not generate documentation for it.
  • @nameThe name of the class/method.
  • @descriptionDescription of the class/method.
  • @paramParameters of the class/method that can be defined repeatedly.
  • @returnThe return type of the class/method.
  • @linkCreate hyperlinks for which you can link to other sections when the document is generated.
  • @exampleCreate examples.

Named Paths (Namepaths)

In case you haven’t noticed, the example above uses Application#initialize to represent an instance method. If it’s a static method, how should it be represented? JSDOC has its own parsing rules:

  • Constructor.MethodRepresent static methods
  • Constructor#MethodPresentation instance method
  • Constructor~MethodRepresent internal methods

With that in mind, you can document your JavaScript code in JSDOC. Go ahead and try it out!

6.1 SAMPLE JS file comments

/ * * *@class
 * @name Application
 * @description Base Class of Application.
 * @param {Element} canvas The canvas dom element.
 * @param {Object} options The options of Application. See {@link Option} for detail.
 * @return {Application}
 *
 * @example* // create your application * new Application(canvas, options); * /
export default class Aplication {

  / * * *@private
   * @function
   * @name Application#intialize
   * @param {number} y - The y value.
   * @description Initialize the application.
   */
  initialize(){}/ * * *@param {number} page- page *@description Initialize the application.
   */
  initialize(){}}Copy the code

7 Reference Materials

  • Github.com/jsdoc3/jsdo…
  • usejsdoc.org/
  • Scarletsky. Making. IO / 2017/12/23 /…

Reference documentation

  • Write JavaScript documents in JSDOC

  • JSDoc – JSDoc (super easy js document generation tool)

  • HTML Chinese-Jsdoc document