jsodoc
v1.0.5
Published
JSON Code comments and documentation generator
Downloads
17
Readme
JSODOC v1.0.4
JSON Code comments and Documentation generator
Coming Soon 1: Dynamically Generate Documentation Website
This is on the agenda, but for now JSODoc is currently only handling github documentation generation. Want it sooner? Donate.
What can it do? (It generated this readme.md)
JSODoc currently generates documentation in github markup. You can also get the documentation in JSON format so you can do anything you want with it. It can process any file type which supports // as code comments.
It supports class's, methods, inputs & return definitions
Quick Summary
Installs
npm i -D JSODOC
Create file: ./docs/template.md
# <b>Project v[[version]]</b>
## <b>Author: </b> [[email]]
## <b>Available class's & Methods</b>
[[jsodoc-git-summary]]
# <b>Documentation</b>
[[jsodoc-git-docs]]
Create file: build.js
const { JSODoc } = require("jsodoc");
const version = require("./package.json").version;
console.clear()
let subs = {
"[[version]]":version,
"[[author]]":"[email protected]"
}
new JSODoc({
dir: './src',
recursive: true,
ext: 'js',
template: './docs/template.md',
substitutions: subs,
output: './tests/test.md'
})
Run build script
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?
Tiny example 1:
// JSODOC = {
// "method": "enableLogging"
// } JSODOC
Tiny example 2:
// JSODOC = {
// "class": "Vector3",
// "info": "Deals with vectors baby!"
// } JSODOC
Medium example 1:
// 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
Full example 1:
// 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
Full example 2 (simple params, methods and returns (non object returns)):
// 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
String mode
This allows you to feed JSODoc a string and parse that string for JSODOC comments.
let str = `// JSODOC = {
// "method": "enableDebug",
// "info": "Enables debugging.",
// "example": [
// "enableDebug();"
// ]
// } JSODOC`;
new JSODoc({
comments: str,
output: './test.md'
})
Files mode
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'
})
Directory mode
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
# <b>Project v[[version]]</b>
## <b>Available class's & Methods</b>
[[jsodoc-git-summary]]
# <b>Documentation</b>
[[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
# <b>Project v[[version]]</b>
## <b>Available class's & Methods</b>
[[jsodoc-git-summary]]
# <b>Documentation</b>
[[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}))
Information
Comment generation from JSON comments.
Parameters
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
- files
Example
// npm i -D aftc-node-tools
// npm i -D jsodoc
const { 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]]':'[email protected]'
}
new JSODoc({
dir: './src',
recursive: true,
ext: 'js',
template: './docs/template.md',
substitutions: mySubs,
output: './tests/test.md'
})
log('Building script completed!'.green)