Security News
tea.xyz Spam Plagues npm and RubyGems Package Registries
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
nodoc
Advanced tools
Readme
A simple and 'low-level' source code comments parser and documentation generator.
Oops, this doc is generated by nodoc itself !
Other languagage, especially javascript, will be supported soon.
Use lower case, used both for language option and extname recognization.
{
"coffee": "coffee",
"coffeescript": "coffee",
"js": "javascript",
"javascript": "javascript"
}
```javascript
{
name: 'parseFile',
description: 'Parse source code from file. Use Promise instead of callback',
tags: [ [Object], [Object], [Object], [Object] ], // tag objects array
lineNum: 78
}
```
#### Tag Object
```javascript
{
tagName: 'param',
type: 'string', // only @param, @property, @option, @return
name: 'srcPath', // only @param, @property, @option
description: 'Path of source code file'
}
```
Tags are only key-value pairs, except `@param`, `@return`, `@property`, `@option`. They may have extra type and (maybe) name.
```javascript
var doc = require('nodoc');
// From file
doc.parser.parseFile('./src/parser/index.coffee').then(function(res){});
res = doc.parser.parseFileSync('./src/parser/index.coffee')
//From source code
doc.parser.parse('A piece of source code', 'coffee').then(function(res){});
```
0. Generate gitHub flavored markdown API doc from comments.
```javascript
var doc = require('nodoc'),
fs = require('fs');
doc.generate('./src/parser/index.coffee', {
moduleName: 'parser',
moduleDesc: 'This is a parser!'
}).then(function(markdown){
fs.writeFileSync('./api.md', markdown);
});
```
In this case, predefined tags will make effects.
### Predefined tags
+ `@private`: Hidden in the generated document.
+ `@nodoc`: Same behavior as `@private`, but they are differ in semantics.
+ `@alias`: Shown as an addition of function name.
+ `@prefix`: Add a custom prefix to function name.
+ `@noPrefix`: Only preserve the real name, regard `util.promisify` as `promisify`.
Of course, you need to write your comments in a standard way to make a parser work. Such as:
###*
* Generate formatted markdown API document from source code
* @param {string} srcPath Path of source code file
* @param {Object={}} opts Options, optional
* @return {Promise} Resolve formatted markdown
* @example
* ` ``javascript
* nodoc.generate('./src/index.coffee').then(function(md){
* console.log(md);
* });
* ` ``
###
As you can see, you can use markdown in your comment!
Reference: jsdoc
Generate formatted markdown API document from source code
param: srcPath
{ string }
Path of the source code file
param: opts
{ Object= }
Options
{
moduleName: '', // module name of the file, or it will be auto set to file name, of parent directory name for `index` file.
moduleDesc: '', // module decription
template: '', // custom template
tplData: {}, // addition template data
cwd: process.cwd() // current working directory
language: '' // specify the language, or it will be auto recognized by extname
rule: {} // specific parser rule, items vary from parsers
}
return: { Promise }
Resolve markdown
example:
nodoc.generate('./src/index.coffee').then(function(md){
console.log(md);
});
Parser module, see below for details.
Create a new parser or override an old ones
param: name
{ string|Array }
parser's name/language (and aliases)
param: parser
{ Object }
parser object, see below
Parse source code directly.
param: source
{ string }
source code
param: language
{ string }
specify source language
param: opts
{ Object= }
option, optional
return: { Array }
parsed comments object array
example:
nodoc.parser.parse("This is source code with comments", "coffee").then(function(comments){
console.log(comments);
})
Parse source code from file. Use Promise instead of callback
param: filePath
{ string }
souce file path
param: opts
{ Object={} }
options
return: { Promise }
resolve parsed comment object array
example:
nodoc.parser.parseFile("index.coffee", {cwd: './src'}).then(function(comments){
console.log(comments);
});
Synchronous version of parseFile
return: { Array }
parsed comment object array
Set parser's rule
param: language
{ string }
parser's name/language
param: rule
{ Object }
parser's rule object
example:
nodoc.parser.setRule('coffee', {
commentReg: /#?([\s\S]+?)#\s+([\w\.]+)/g
});
Nodoc uses underscore template to render the markdown template. You need to realize that template is not HTML's privilege. If you don't want to use the default template, you can use your own.
doc.generate('./src/parser/index.coffee', {
template: 'Here is your own template'
tplData: {} // You can use this object to add custom data to your template
}).then(function(markdown){});
However, if you even want to use a alternative template engine, please use parser module directly.
If the languages you use is not supported by nodoc, you can write your own parser and register it by parser.setParser
. If you want your parser to be a part of nodoc, please make a pull request, it is warmly welcomed.
A parser should provide follow APIs:
Parse comment from source code
param: source
{ string }
source code
param: localRule
{ Object= }
optional, custom rule object, use once
return: { Array }
parsed comments object array
Set the rule of the parser
param: ruleObj
{ Object }
rule object
Hmm..., I'd like to use this to generate document.
return: { Object }
rule object
A parser uses and is supposed to expose the rules it uses to parse the code.
{ commentReg: /###\*([\s\S]+?)###\s+([\w\.@'"]+)/g,
splitReg: /^\s+\* ?@/m,
tagNameReg: /^([\w\.]+)\s*/,
typeReg: /^\{(.+|}?)\}\s*/,
nameReg: /^([\w\.]+)\s*/,
nameTags: [ 'param', 'property', 'option' ],
descriptionReg: /^([\s\S]*)/,
removePrefix: /self\.|this\.|@|'|"/g }
MIT
FAQs
A simple and 'low-level' source code comments parser and gitHub flavored markdown API documentation generator.
The npm package nodoc receives a total of 10 weekly downloads. As such, nodoc popularity was classified as not popular.
We found that nodoc demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.