docs-parser
v0.0.2
Published
Documentation parser, adapts to any language and will help you document all the things.
Downloads
44
Maintainers
Readme
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.
- Come up with a name for the project
- 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>