Doc-holiday is a source-code documentation generation management system for JavaScript / TypeScript source modules.
You may already use, or may have used source-code documentation generation tools in the past, and if so you know that the proposition usually falls short of its promise and expectation.
The JSDOC standard was created years ago, in the infancy of JavaScript, where there were dozens of ways of doing pretty much the same things, but no good way to explain what it is you had done.
As a result, JSDOC specifies nearly 70 tags designed to categorize and describe some bit of code or another.
Specifying these tags is for the most part tedious and redundant. Modern
JavaScript, and especially TypeScript code has unambiguous syntax conventions
that specify code entities in context. And JSDOC honors some of this.
For example, if you use the class keyword to declare a class,
there is no need to further note it with the @class tag, as you
would need to do if you were creating a class by building it as a function
prototype explicitly. Similarly, there’s no need to use the @function or
@name tags with a classically declared function. But other things are not
so clear. What about properties of a class? Typedefs? Enums? These things
can be documented in JSDOC, but it’s often a battle to get it to work
the way you would like.
Doc-holiday uses a different approach. It does not replace JSDoc – In fact, you will need to have JSDoc or one of the supported alternatives installed before you can use Doc-holiday as designed.
Instead, doc-holiday parses your source code for its code declarations and generates intermediate ‘stub’ files that capture the metadata already present in your code and creates corresponding JSDoc comment blocks with the correct tags, and that is what is sent to the JSDoc-compatible renderer to produce the output.
Of course, if you have comment descriptions for your code entities, these are also represented via the stub to the output.
This includes side-adjacent comments too, so
expoort const foo = 'FOOBAR' // define our FOOBAR constant
will capture all the relevant information that can be gleaned from this statement in code and produce the JSDoc stub
/**
* @constant {string} foo
* defines our FOOBAR constant
* @default 'FOOBAR'
*
* @public
*/
var foo = 'FOOBAR'
Which will render according to your rendering engine preferences and chosen template to produce something like:
stringdefines our FOOBAR constant
Default: "'FOOBAR'"
Access: public
If you use TypeScript, then it gets even better, because your parameter and return
types are read from your code and echoed in @param {type} name
and @return {type} tags.
Combined with using side-adjacent comments, you can write typescript code like this:
// Calculates the biorythm of the named indiidual
// using their birthdate as the starting point
export function computeBiorhythm(
name:string, // The user's name
birthdate: Date // the user's birthdate
// (time portion of date ignored)
):BiorhythmData // computed object returned
{
// ... awesome code here...
}
and get this type of output:
Calculates the biorythm of the named indiidual using their birthdate as the starting point
Kind: inner method of example
Returns: BiorhythmData - <p>computed object returned</p>
Access: public
| Param | Type | Description |
|---|---|---|
| name | string |
<p>The user’s name</p> |
| birthdate | Date |
<p>the user’s birthdate (time portion of date ignored)</p> |
@param and @return tags// /* or /** (jsdoc-style) blocksnumber be a positive integer between 0-100?
A constraint will allow you to specify that, and much more. See Introducing Constraints