And now you can run your jsdoc command and parse TypeScript files.
How it works?
It performs 4 operations:
First of all it transpiles all .ts and .tsx files to .js, so that all comments used by you are treated
as a regular JSDoc comments.
Furthermore it:
Converts all your commented type aliases to @typedef
Converts all your commented interface definitions to @interface,
Converts descriptions for your public, protected, static class members
so they can be printed by JSDoc automatically.
Examples
/**
* ActionRequest
* @memberof Action
* @alias ActionRequest
*/
export type ActionRequest = {
/**
* parameters passed in an URL
*/
params: {
/**
* Id of current resource
*/
resourceId: string;
/**
* Id of current record
*/
recordId?: string;
/**
* Name of an action
*/
action: string;
[key: string]: any;
};
}
is converted to:
/**
* ActionRequest'
* @memberof Action'
* @alias ActionRequest'
* @typedef {object} ActionRequest'
* @property {object} params parameters passed in an URL'
* @property {string} params.resourceId Id of current resource'
* @property {string} [params.recordId] Id of current record'
* @property {string} params.action Name of an action'
* @property {any} params.{...}'
*/
Also you can comment the interface in a similar fashion:
/**
* JSON representation of an {@link Action}
* @see Action
*/
export default interface ActionJSON {
/**
* Unique action name
*/
name: string;
/**
* Type of an action
*/
actionType: 'record' | 'resource' | Array<'record' | 'resource'>;
/**
* Action icon
*/
icon?: string;
/**
* Action label - visible on the frontend
*/
label: string;
/**
* Guarding message
*/
guard?: string;
/**
* If action should have a filter (for resource actions)
*/
showFilter: boolean;
/**
* Action component. When set to false action will be invoked immediately after clicking it,
* to put in another words: there wont be an action view
*/
component?: string | false | null;
}
or describe your class properties like that:
/**
* Class name
*/
class ClassName {
/**
* Some private member which WONT be in jsdoc (because it is private)
*/
private name: string
/**
* Some protected member which will go to the docs
*/
protected somethingIsA: number
/**
* And static member which will goes to the docs.
*/
static someStaticMember: number
public notCommentedWontBeInJSDoc: string
constructor(color: string) {}
}
@category plugin
better-docs also allows you to nest your documentation into categories and subcategories in the sidebar menu.
Usage
To add a plugin - update plugins section in your jsdoc.json file:
and then you can use @category and/or @subcategory tag in your code:
/**
* Class description
* @category Category
* @subcategory All
*/
class YourClass {
....
}
@component plugin [BETA]
Better-docs also allows you to document your React and Vue components automatically. The only thing you have to do is to add a @component tag. It will take all props from your components and along with an @example tag - will generate a live preview.
Installation instructions
Similar as before to add a plugin - you have to update the plugins section in your jsdoc.json file:
In this case, props will be taken from props property.
Preview
@component plugin also modifies the behaviour of @example tag in a way that it can generate an actual component preview. What you have to do is to add an @example tag and return component from it:
You can put as many @example tags as you like in one component and "caption" each of them like this:
/**
* @component
* @example <caption>Example usage of method1.</caption>
* // your example here
*/
Mixing components in preview
Also you can use multiple components which are documented with @component tag together. So lets say you have 2 components and in the second component you want to use the first one as a wrapper like this:
Most probably your components will have to be run within a particular context, like within redux store provider or with custom CSS libraries.
You can simulate this by passing a component.wrapper in your jsdoc.json:
(To read more about passing options - scroll down to Customization section)
@component plugin creates an entry file: .entry.js in your docs output folder. Sometimes you might want to add something to it. You can do this by passing: component.entry option, which is an array of strings.
So let's say you want to add babel-polyfill and 'bulma.css' framework to your bundle. You can do it like this:
Within the better-docs folder run the gulp script. It will regenerate documentation every time you change something.
It supports following EVN variables:
DOCS_COMMAND - a command in your root repo which you use to generate documentation: i.e. DOCS_COMMAND='jsdoc -c jsdoc.json' or npm run docs if you have docs command defined in package.json file
DOCS_OUTPUT - where your documentation is generated. It should point to the same folder your jsdoc --destination conf. But make sure that it is relative to the path where you cloned better-docs.
DOCS - list of folders from your original repo what you want to watch for changes. Separated by comma.
cd better-docs
DOCS_COMMAND='npm run docs' DOCS=../src/**/*,../config/**/* DOCS_OUTPUT=../docs cd better-docs && gulp
The script should launch the browser and refresh it whenever you change something in the template or in DOCS.
Setting up the jsdoc in your project
If you want to see how to setup jsdoc in your project - take a look at these brief tutorials: