docs-parser

Docs

Docs, addapts to any language and will help you document all the things. Where there is development there is a need for documentation. There are several great libraries for all sorts of files, written by brilliant developers, libraries like SassDoc, JSDoc, JavaDoc, Jazzy, StyleDocco, KSS, Hologram, DSS and several more. All of these libraries do a very good job for documenting their respective languages. However there are very few projects that only require 1 file type. Which means if you really want to document all your code you may have to use 3 or 4 of these documentation generators. Each of the generators have their own way of documenting and their annotations, and their own document site which just makes it harder to keep all your documentation in one spot.

Docs fixes all these issues by giving you the ability to generate documentation for all your files. While giving you control over what annotations you want to use in each file type.

Options

files: file globs to be parsed to get the documentation default

[ 'app/**/*', 'src/**/*', '*.md' ]

ignore: files globs to be ignored default

[
  '.*', // all dot files
  'node_modules/', 'bower_components/', 'jspm_packages/', // package managers
  'dist/', 'build/', 'docs/', // normal folders
  'tests/', 'coverage/' // unit tests and coverage results
]

watch: when true it will watch files for changes default false

raw: Will return the raw data by file, aka data won't be sorted default false

languages: This is an object of comment styles for various languages. default

{
  // annotation identifier that can be change on a file specific basis if needed.
  // While this is a setting, it probably should probably never be changed. If it does
  // need to be changed it should be changed to be a special character.
  prefix: '@',
 
  // header comment style
  // @note {10} only 1 of these can be used per file
  header: { start: '////', line: '///', end: '////', type: 'header' },
 
  // body comment style
  body: { start: '', line: '///', end: '', type: 'body' },
 
  // inline comments for body comments
  inline: { start: '', line: '///#', end: '', type: 'inline' },
 
  // this is used for any interpolations that might occur in annotations.
  // I don't see this needing to change but just incase I'm making it a setting.
  // @note {10} This setting is used to create a RegExp so certain characters need to be escaped
  interpolation: {
    start: '\\${',
    end: '}'
  },
}

for other predefined languages see the defined languages

Usage

import parser from 'docs-parser'
import fs from 'fs-extra-promisify'
 
parser({ files: 'app/**/*' })
  .then((data) => fs.outputJson('docs/docs.json', data))

Adding a annotation

documentation for it is coming soon (if your curious just look at src/annotations/*)

Default Annotations

See more on the default annotations

Documenting your items

There are 3 different types of comment blocks block level, and file level.

Note: the comments below are using the comment defaults which are slashes please see defined languages for other language specific comment styles

Header comment

This type of comment can only occur once per file. Any annotations that are found inside of the file level comment will become the default value for the block level comments. It is very useful when you have a whole file sharing some annotations (@author, @page and so on).

//// 
/// @author Tyler Benton 
/// @page functions/numbers 
/// @description Useful number functions 
//// 

Body comment block

This type of comment is used multiple times per file.

/// @author Tyler Benton 
/// @page functions/numbers 
/// @description 
/// This function does something awesome, I swear. 
@function some-function(){
  // ... 
}

Inline comment

This type of comment is used to extend a body comment block

/// @name happypanda 
/// @type {object} 
const happypanda = {
  smile() { ///# @property {function} happypanda.smile - This makes the panda smile 
    return 'smile'
  },
}

Todo

• Look into adding a callback function that runs after the block has been completely parsed this would be run after the single line comments are parsed. I'm not sure how useful this would be but it's a thought.

  • This could allow you to create your own data structure.

• Look into being able to reference a different language comment style withing the existing language. For example this would allow you to write JS documentation inside of an HTML document

  <script>
  <!---{js}
   @name something awesome
   @description
   Lorem ipsum dolor sit amet, consectetur adipisicing elit. Vitae praesentium voluptates beatae ducimus dolore velit excepturi maiores delectus doloribus labore totam odio culpa, magni reprehenderit est similique aspernatur dolor rerum?
  ---->
  </script>