JSON Code comments and documentation generator
npm install jsodoc
npm i -D JSODOC
`
$3
`
Project v[[version]]
Author: [[email]]
Available class's & Methods
[[jsodoc-git-summary]]
Documentation
[[jsodoc-git-docs]]
`
$3
`
const { JSODoc } = require("jsodoc");
const version = require("./package.json").version;
console.clear()
let subs = {
"[[version]]":version,
"[[author]]":"darcey.lloyd@gmail.com"
}
new JSODoc({
dir: './src',
recursive: true,
ext: 'js',
template: './docs/template.md',
substitutions: subs,
output: './tests/test.md'
})
`
$3
`
node build
`
Remember to add to your comments to your src files in the JSODOC way or it wont generate anything (examples of this are below).
How do I add JSODOC comments to my files?
$3
`
// JSODOC = {
// "method": "enableLogging"
// } JSODOC
`
$3
`
// JSODOC = {
// "class": "Vector3",
// "info": "Deals with vectors baby!"
// } JSODOC
`
$3
`
// JSODOC = {
// "class": "AFTCColor",
// "info": "Color handing utility.",
// "link": "https://aftc.io",
// "returns":
// {
// "type": "array",
// "info": "Array of colors."
// },
// "example": [
// "/ Use this comment style /",
// "enableDebug1();"
// ]
// } JSODOC
`
$3
`
// JSODOC = {
// "class": "BlowUpTheMoon",
// "info": "Nukes the moon.",
// "link": "https://aftc.io",
// "params": [
// {
// "type": "object",
// "def": [
// { "name": "Obj1Param1", "required": true, "default": null, "info": "Info..." },
// { "name": "Obj1Param2", "required": true, "default": null, "info": "Info..." },
// { "name": "Obj1Param3", "required": true, "default": null, "info": "Info..." }
// ]
// },
// {
// "name": "arrayParam",
// "type": "array",
// "required": true,
// "default": null,
// "info": "Info..."
// }
// ],
// "methods": [
// {
// "name": "updateConfig",
// "params": [
// { "name": "Obj1Param1", "type": "String", "required": true, "default": null, "info": "Info..." },
// { "name": "Obj1Param2", "type": "Boolean", "required": true, "default": null, "info": "Info..." },
// { "name": "Obj1Param3", "type": "Number", "required": true, "default": null, "info": "Info..." }
// ],
// "returns": "Boolean"
// },
// {
// "name": "start"
// },
// {
// "name": "stop"
// },
// {
// "name": "getMessage",
// "returns": "string"
// }
// ],
// "returns": {
// "type": "object",
// "def": [
// { "name": "ObjParam1Name", "type": "string", "info": "Info..." },
// { "name": "ObjParam2Name", "type": "string", "info": "Info..." },
// { "name": "ObjParam3Name", "type": "string", "info": "Info..." }
// ]
// },
// "example": [
// "// Code comment test 1",
// "/ Code comment test 2/",
// "enableDebug1();"
// ]
// } JSODOC
`
$3
`
// JSODOC = {
// "method": "drawBox",
// "info": "Draws a box.",
// "params": [
// {
// "name": "width",
// "type": "number",
// "required": true,
// "default": null,
// "info": "The width of your box in pixels"
// },
// {
// "name": "height",
// "type": "number",
// "required": true,
// "default": null,
// "info": "The height of your box in pixels"
// }
// ],
// "methods": [
// {
// "name": "clear"
// },
// {
// "name": "dispose"
// }
// ],
// "returns":
// {
// "type": "Element",
// "info": "Canvas with box drawn on it."
// },
// "example": [
// "// Code comment test 1",
// "/ Code comment test 2/",
// "let canvas = drawBox(100);"
// ]
// } JSODOC
`
You use what you want, JSODoc will generate what it is given...
Tips
- Tip 1 - Want to get started quickly?
Pick one of the above examples, copy it and paste it above your method or class in any language source file js, php etc that supports // code comments and edit away.
- Tip 2 - Easy editing and editor validation and support
Select/highlight your JSODOC comment block and uncomment the whole block, VSCode and others editors will highlight syntax errors (ignore ending "} JSODOC" line as that will cause an error). Then when your done editing select the comment block again and comment it out again. You must use // not / / or / * / commenting types
- Tip 3 - Errors and Invalid JSON syntax
Typically a "," is in the wrong place, at the end of one of your end entries, JSON does't parse it, so JSODOC won't either.
I find it best to select the whole comment block, use your editors comment/uncomment shortcut and check for validation errors. Make sure you got no trailing , where they shouldn't be eg:
`
Incorrect: {"hello",} Correct: {"hello"}
Incorrect: ["a","b",] Correct: ["a","b",]
Incorrect: [1,2,] Correct: [1,2]
`
`
Incorrect:
{
"color": "#FFCC00"},
}
Correct:
{
"color": "#FFCC00"}
{
`
`
Incorrect:
[
{ "color": "#FFCC00"},
{ "color": "#FFCC00"},
]
Correct:
[
{ "color": "#FFCC00"},
{ "color": "#FFCC00"}
]
`
If your having trouble entering the comments or have build errors, then your json syntax is probably incorrect.
Simply uncomment the JSODOC block in VSCode or your editor of choice, ignore the errors on the first and last lines, VSCode and other IDE's will still validate the JSON inbetween. Careful about trailing commas "," json doesn't parse them, so JSODOC can't either.
Generating documentation from your source files
JSODOC Can work in 3 modes:
- String
- Files
- Directory
$3
This allows you to feed JSODoc a string and parse that string for JSODOC comments.
`
let str = // JSODOC = {
;
new JSODoc({
comments: str,
output: './test.md'
})
`
$3
This allows you to feed JSODoc an array of file paths and JSDOC will read those files and parse for JSDOC comments.
`
new JSODoc({
files: ['./src/file1.js'],
template: './docs/template.md',
substitutions: subs,
output: './readme.md'
})
`
$3
This allows you to feed JSODoc a path, a file extension or "*" for all files and to whether or not to recursively search through all folders in the specified directory. It will then parse each file for JSDOC comments.
`
new JSODoc({
dir: './src',
recursive: true,
ext: 'js',
template: './docs/template.md',
substitutions: subs,
output: './tests/test.md'
})
`
Generating a readme.md and using a template file
You can supply JSODOC with a template.md file which can be used as a template and JSODOC will substitute it's documentation into specific markers within that template.md file.
Template example
`
Project v[[version]]
Available class's & Methods
[[jsodoc-git-summary]]
Documentation
[[jsodoc-git-docs]]
`
JSODOC will substitute the class & method summary into [[jsodoc-git-summary]]
JSODOC will substitute the main documentation into [[jsodoc-git-docs]]
You will notice that [[version]] is in the template, this is for user substitutions, all you have to do is supply an object key value pair with your own substitutions.
User substitutions
You just supply an object with your own key value pairs to substitute. You must supply a template file for this to work, if no template file is supplied JSODOC will simply generate the file automatically with a class & method summary and the docs it generated.
`
// This will substituate the marker [[version]] with 1.4.2 in ./docs/template.md
let mySubs = {
"[[version]]": "1.4.2"
}
new JSODoc({
dir: './src',
recursive: true,
ext: 'js',
template: './docs/template.md',
substitutions: mySubs,
output: './tests/test.md'
})
`
Setting up your build script and how to build your docs
- Create folder docs
- Create file in there called template.md and set it up to look something like
`
Project v[[version]]
Available class's & Methods
[[jsodoc-git-summary]]
Documentation
[[jsodoc-git-docs]]
`
- Setup you user Substitutions
`
// get version from package.json
const version = require("./package.json").version;
// Setup my subs
let mySubs = {
"[[version]]",version
}
`
- Start JSODOC to process your src directory
`
new JSODoc({
dir: './src',
recursive: true,
ext: 'js',
template: './docs/template.md',
substitutions: mySubs,
output: './tests/test.md'
})
`
- And finally run your build script from terminal/cmd/cli using node
`
node build
`
JSODOC - Generated documentation
Available Methods & Class's:
- JSODoc({object})
JSODoc({object}))
$3
Comment generation from JSON comments.$3
- Object:
- files
- Required: false
- Default: false
- Info: For using JSODoc in files mode
- dir
- Required: false
- Default: false
- Info: For using JSODoc in directory mode
- recursive
- Required: false
- Default: false
- Info: Directory mode recursive scan on or off
- ext
- Required: false
- Default: null
- Info: Directory mode extensions of files to use
- template
- Required: false
- Default: false
- Info: If you want JSODOC to use a template and sustitute into it
- substitutions
- Required: false
- Default: false
- Info: User substitutions object (key value pairs)
- output
- Required: false
- Default: ./readme.md
- Info: The full path to the .md file to create/write to
$3
`
// npm i -D aftc-node-tools
// npm i -D jsodocconst { log, cls } = require('aftc-node-tools');
const { JSODoc } = require('./jsodoc');
const version = require('./package.json').version;
cls();
log('Building script starting!'.green)
let subs = {
'[[version]]':version,
'[[author]]':'darcey.lloyd@gmail.com'
}
new JSODoc({
dir: './src',
recursive: true,
ext: 'js',
template: './docs/template.md',
substitutions: mySubs,
output: './tests/test.md'
})
log('Building script completed!'.green)