npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

jsodoc

v1.0.5

Published

JSON Code comments and documentation generator

Downloads

17

Readme

JSODOC v1.0.4

JSON Code comments and Documentation generator

Donate

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

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)