cod
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*/
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
There are also numbers and strings, and you can explicitly set a flag to false
:
@number 42
@string Hello there.
@boolean false
Structure is designated by indentation.
@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.
Specifying a @tag
more than once will turn it into a list of values.
@list A
@list B
@list C
@tags:like:this
are equivalent to nested tags.
@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
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 whentext
is not supplied
var cod = ;var doc; doc = ; consoledirdoc; // Output:// { '!text': 'Hello, cod.', 'answer': 42 }
var fs = cod = ; // file.coffee://// ###*// Hello, cod.// @answer 42// ###// fs ; // Output:// {"!text":"Hello, cod.","answer":42}
install
npm install -g cod
license
MIT