xpf0000/docs

Generate documents from standard comments, Not limited to specific files, specific languages

Docs

Generate documents from standard comments, Not limited to specific files, specific languages

group by user custom, show file's dependencies chain that used by import and require

https://xpf0000.github.io/docs.github.io/

Install

npm install @xpf0000/docs
docs
docs src
docs src --build outSrc

How it works

Traverse all files in the directory, find all standard comments like /* */

Resolve specific tags starting with @, like @author @name @desc @type

Resolve import and require to get file's dependencies chain

Comment Example

/**
 * @doc true
 * @fileDoc true
 * @author xupengfei
 * @name Utils.js
 * @type core
 * @desc global method extend
 */
const fs = require('fs')
const path = require('path')

/**
 * @doc true
 * @name findFile
 * @desc find all file by location dir path
 * @param base location dir path
 * @returns [] all file in location dir path
 */
const findFile = (base) => {
  const files = []
  fs.readdirSync(base).forEach((file) => {
    const curPath = path.join(base, file)
    if (fs.existsSync(curPath)) {
      const stat = fs.lstatSync(curPath)
      if (!stat.isSymbolicLink()) {
        if (stat.isFile()) {
          files.push(curPath)
        } else if (stat.isDirectory()) {
          const sub = findFile(curPath)
          files.push(...sub)
        }
      }
    }
  })
  return files
}

/**
 * @doc true
 * @name uuid
 * @desc make uuid string
 * @param length uuid string length
 * @returns string uuid string
 */
const uuid = (length = 32) => {
  const num = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890'
  let str = ''
  for (let i = 0; i < length; i++) {
    str += num.charAt(Math.floor(Math.random() * num.length))
  }
  return str
}

module.exports = {
  findFile,
  uuid
}

Comment Tags

@doc

is parse to doc

@fileDoc

Documentation of the entire file

@type

comment doc's type, doc's group by this

@author

current comment doc's author

@name

file's name, method's name, ...

@desc

current comment doc's desc

@param

current comment doc's param

@returns

current comment doc's returns