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

cod

v0.4.3

Published

An unopinionated documentation generator.

Downloads

20

Readme

cod Build Status Module Version Dependency Status

An unassuming documentation format that works with any language.


/**
@Example
  Text can go anywhere.
     Whitespace is preserved.
  @flag
  @number 42
  @string Hello, cod
  @nested
    @property yay
    Nested text.
  @list A
  @list B
  @list C
*/
{
  "Example": {
    "!text": "Text can go anywhere.\n   Whitespace is preserved.",
    "flag": true,
    "number": 42,
    "string": "Hello, cod",
    "nested": {
      "!text": "Nested text.",
      "property": "yay"
    },
    "list": ["A", "B", "C"]
  }
}

stupid by design

cod is not a documentation generator.

It is a documentation format that outputs nearly "1-to-1" JSON.

cod does zero code analysis.

cod doesn't know what @class, @return, @param or @any @other tag means.

cod does not generate HTML, PDFs, or any traditionally human-readable documentation; that part is left up to you.

As such, cod is not a standalone replacement for tools like doxygen or Sphinx, but it functions as the first step in a more flexible doc-generation process for those who need finer control.

cod may not be smart, but it's not stubborn, either.

You write your docs in cod's format, and it faithfully outputs JSON. That's it.

Use whatever tags you need.

Anything that isn't a @tag is text.

Text sections are left untouched. You can process it as Markdown later. Or HTML. Or just keep it as plain text.

Once you have the JSON, use it however you like:

  • Utilize existing templates and styles.
  • Build an app that can consume multiple versions of your API docs.
  • Easily compare specific versions of your API at the structural level.

cod is naturally language-agnostic; all it needs to know is the pattern you use to denote a doc-block (i.e. /** and */).

format

Tags without values are treated as boolean flags:

@flag
{
  "flag": true
}

There are also numbers and strings, and you can explicitly set a flag to false:

@number 42
@string Hello there.
@boolean false
{
  "number": 42,
  "string": "Hello there.",
  "boolean": false
}

Structure is designated by indentation.

@root
  @nested value
{
  "root": {
    "nested": "value"
  }
}

Whitespace after indentation is preserved in text blocks.

@example
  This is some example text.

  It can handle multiple lines.
    Indentation is preserved.
{
  "example": {
    "!text": "This is some example text.\n\nIt can handle multiple lines.\n  Indentation is preserved."
  }
}

Specifying a @tag more than once will turn it into a list of values.

@list A
@list B
@list C
{
  "list": [
    "A",
    "B",
    "C"
  ]
}

@tags:like:this are equivalent to nested tags.

@root:inline:nested value
{
  "root": {
    "inline": {
      "nested": "value"
    }
  }
}

Values of tags that have nested properties or text bodies are stored as @complexProperty["!value"].

@simpleTag 100

@complexTag This will be stored as example["!value"]
  This allows for nested text and tags.
  @likeThis
{
  "simpleTag": 100,
  "complexTag": {
    "!value": "This will be stored as example[\"!value\"]",
    "!text": "This allows for nested text and other properties.",
    "likeThis": true
  }
}

CLI

cod *.js # or *.go or *.c or ...
cod -b '###*' -e '###' *.coffee
cod -b "'''*" -e "'''" *.py
cod -b '{-*' -e '-}' *.hs
cod -b '--[[*' -e ']]' *.lua
cat *.js | cod  > api.json
cod --help
              ,
           _-""-,-"'._         
     .-*'``           ``-.__.-`:
  .'o   ))` ` ` ` ` ` `_`.---._:
   `-'.._,,____...--*"` `"     
         ``
cod: An unassuming documentation generator.

Usage:
  cod [-b <doc-begin> -e <doc-end>] [-o <output-file>] [-u] [<input-file>...]
  cod -h | --help | --version

Options:
  -b <doc-begin>    String that marks the start of a doc-block [default: /**]
  -e <doc-end>      String that marks the end of a doc-block [default: */]
  -o <output-file>  Output file [default: STDOUT]
  -u --ugly         Output non-pretty JSON.
  -v --version      Show version.
  -h --help         Show this screen.
  <input-file>...   File(s) containing docs. If none, cod reads from STDIN.

gulp

See gulp-cod.

Grunt

Create an issue if you make a Grunt plugin for cod, and I'll list it here.

API

cod([[text,] options])

If text is supplied, cod will parse it and return a plain JS object that contains your doc structure.

Otherwise, cod will return a Transform stream into which your source can be piped. cod will buffer the stream until completion, after which it will output the stringified JSON of your doc's structure.

text (String | Buffer)

Text containing cod-style documentation. Probably source code.

options (Object)

docBegin (String) default: "/**"

String that marks the start of a doc-block

docEnd (String) default: "*/"

String that marks the end of a doc-block

pretty (boolean) default: true

Format the JSON output with JSON.stringify(doc, null, 2) Only applicable in stream mode when text is not supplied

var cod = require('cod');
var doc;

doc = cod([
  '/**',
  'Hello, cod.',
  '@answer 42',
  '*/'
].join('\n'));

console.dir(doc); 

// Output:
// { '!text': 'Hello, cod.', 'answer': 42 }
var fs = require('fs'),
    cod = require('cod');

// file.coffee:
//
// ###*
// Hello, cod.
// @answer 42
// ###
//

fs.createReadStream(__dirname + '/file.coffee')
  .pipe(cod({
    docBegin: '###*',
    docEnd: '###',
    pretty: false
  }))
  .pipe(process.stdout);

// Output:
// {"!text":"Hello, cod.","answer":42}

install

npm install -g cod

license

MIT


Analytics