Documentation toolbox for your **javascript** / **typescript** projects based on JSDoc3 with **@category**, **@component** and **@optional** plugins.
This is how it looks:
# Example
Example documentation can be found here: https://softwarebrothers.github.io/example-design-system/index.html
# OpenSource SoftwareBrothers community
- [Join the community](https://join.slack.com/t/adminbro/shared_invite/zt-czfb79t1-0U7pn_KCqd5Ts~lbJK0_RA) to get help and be inspired.
- subscribe to our [newsletter](http://opensource.softwarebrothers.co)
# Installation
```sh
npm install --save-dev better-docs
```
# Theme Usage
## With command line
Assuming that you have [jsdoc](https://github.com/jsdoc/jsdoc) installed globally:
```
jsdoc your-documented-file.js -t ./node_modules/better-docs
```
## With npm and configuration file
In your projects package.json file - add a new script:
```
"script": {
"docs": "jsdoc -c jsdoc.json"
}
```
in your `jsdoc.json` file, set the template:
```json
"opts": {
"template": "node_modules/better-docs"
}
```
# TypeScript support
better-docs has a plugin which allows you to generate documentation from your TypeScript codebase.
## Usage
To use it update your `jsdoc.json` file
```
...
"tags": {
"allowUnknownTags": ["optional"] //or true
},
"plugins": [
"node_modules/better-docs/typescript"
],
"source": {
"includePattern": "\\.(jsx|js|ts|tsx)$",
},
...
```
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:
```
...
"tags": {
"allowUnknownTags": ["category"] //or true
},
"plugins": [
"node_modules/better-docs/category"
],
...
```
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](https://reactjs.org/) and [Vue](https://vuejs.org/) 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:
```
...
"tags": {
"allowUnknownTags": ["component"] //or true
},
"plugins": [
"node_modules/better-docs/component"
],
...
```
Since __component__ plugin uses [parcel](https://parceljs.org) as a bundler you have to install it globally. To do this run:
```
# if you use npm
npm install -g parcel-bundler
# or yarn
yarn global add parcel-bundler
```
## Usage
To document components simply add `@component` in your JSDoc documentation:
```jsx
/**
* Some documented component
*
* @component
*/
const Documented = (props) => {
const { text } = props
return (
{text}
)
}
Documented.propTypes = {
/**
* Text is a text
*/
text: PropTypes.string.isRequired,
}
export default Documented
```
The plugin will take the information from your [PropTypes](https://reactjs.org/docs/typechecking-with-proptypes.html) and put them into an array.
For Vue it looks similar:
```vue
```
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:
**React example:**
```jsx
/**
* Some documented component
*
* @component
* @example
* const text = 'some example text'
* return (
*
* )
*/
const Documented = (props) => {
///...
}
```
**Vue example 1:**
```vue
```
**Vue example 2:**
```vue
```
You can put as many `@example` tags as you like in one component and "caption" each of them like this:
```javascript
/**
* @component
* @example
Documentation toolbox for your **javascript** / **typescript** projects based on JSDoc3 with **@category**, **@component** and **@optional** plugins.
This is how it looks:
We're an open, friendly team that helps clients from all over the world to transform their businesses and create astonishing products.
* We are available for [hire](https://softwarebrothers.co/contact).
* If you want to work for us - check out the [career page](https://softwarebrothers.co/career).