Jsdoc Markdown



Table of Contents

Overview

  • JSDoc Frequently Used annotations. Jsdoc supports following tags and syntax is mentioned. All this syntax should be used included in jsdoc syntax (Adding asterisk to multiline comments) Tag. Usage/Syntax @Author. Adds Author of code, supports to add email. Marks function as a class instance can be created.
  • See what is new in the Visual Studio Code November 2018 Release (1.30).
Jsdoc

JSDoc includes a Markdown plugin that automatically converts Markdown-formatted text to HTML. You can use this plugin with any JSDoc template. In JSDoc 3.2.2 and later, the Markdown plugin uses the marked Markdown parser.

The jsdoc-md command scrapes JSDoc from source files nested in the current working directory to populate a markdown file documentation section. Source files are excluded via.gitignore files. It implements the function jsdocMd and has the following arguments. Jsdoc being the actual JSDoc module, docdash our template and, for the sake of a more thorough example, we will also be rendering our JSDoc documentation as a Markdown file so that we can easily.

Note: When you enable the Markdown plugin, be sure to include a leading asterisk on each line of your JSDoc comments. If you omit the leading asterisks, JSDoc's parser may remove asterisks that are used for Markdown formatting.

By default, JSDoc looks for Markdown-formatted text in the following JSDoc tags:

  • @description (including untagged descriptions at the start of a JSDoc comment)

Enabling the Markdown plugin

To enable the Markdown plugin, add the string plugins/markdown to the plugins array in your JSDoc configuration file:

Converting Markdown in additional JSDoc tags

By default, the Markdown plugin only processes specific JSDoc tags for Markdown text. You can handle Markdown text in other tags by adding a markdown.tags property to your JSDoc configuration file. The markdown.tags property contains an array of the additional doclet properties that can contain Markdown text. (In most cases, the name of the doclet property is the same as the tag name. However, some tags are stored differently; for example, the @param tag is stored in a doclet's params property. If you're not sure how a tag's text is stored in a doclet, run JSDoc with the -X/--explain tag, which prints each doclet to the console.)

For example, if the foo and bar tags accept values that are stored in a doclet's foo and bar properties, you could enable Markdown processing of these tags by adding the following settings to your JSDoc configuration file:

Excluding the default tags from Markdown processing

To prevent the Markdown plugin from processing any of the default JSDoc tags, add a markdown.excludeTags property to your JSDoc configuration file. The markdown.excludeTags property contains an array of the default tags that should not be processed for Markdown text.

For example, to exclude the author tag from Markdown processing:

Hard-wrapping text at line breaks

By default, the Markdown plugin does not hard-wrap text at line breaks. This is because it's normal for a JSDoc comment to be wrapped across multiple lines. If you prefer to hard-wrap text at line breaks, set your JSDoc configuration file's markdown.hardwrap property to true. This property is available in JSDoc 3.4.0 and later.

Adding ID attributes to headings

By default, the Markdown plugin does not add an id attribute to each HTML heading. To automatically add id attributes based on the heading's text, set your JSDoc configuration file's markdown.idInHeadings property to true. This property is available in JSDoc 3.4.0 and later.

Styleguidist generates documentation for your components based on the comments in your source code, propTypes declarations, and Readme files.

See examples of documented components in our demo style guide.

Code comments and propTypes#

Styleguidist will display your components’ JSDoc comment blocks. Also, it will pick up props from propTypes declarations and display them in a table.

importPropTypesfrom'prop-types'
/**
* General component description in JSDoc format. Markdown is *supported*.
exportdefaultclassButtonextendsReact.Component{
/** Description of prop 'foo'. */
/** Description of prop 'baz'. */
baz:PropTypes.oneOfType([PropTypes.number,PropTypes.string])
static defaultProps ={
}
render(){
}

Flow and TypeScript type annotations are supported.

You can change its behavior using propsParser and resolver options.

Component’s PropTypes and documentation comments are parsed by the react-docgen library. They can be modified using the updateDocs function.

Usage examples and Readme files#

Jsdoc Markdown Plugin

Styleguidist will look for any Readme.md or ComponentName.md files in the component’s folder and display them. Any code block with a language tag of js, jsx, or javascript will be rendered as a React component with an interactive playground. For backwards compatibility, code blocks without a language tag are also rendered in this way. It is recommended to always use the proper language tag for new documentation.

<Button size='large'>Push Me</Button>
<Button>I’m transparent!</Button>
Or add padding between examples in a block by passing the `padded` modifier:
```jsx padded
<Button>Click Me</Button>
```
Or disable an editor by passing a `noeditor` modifier:
```jsx noeditor
```
To render an example as highlighted source code add a `static` modifier:
```jsx static
```
Jsdoc Markdown
Examples with all other languages are rendered only as highlighted source code, not an actual component:
```html
```
Any [Markdown](http://daringfireball.net/projects/markdown/) is **allowed** _here_.

You can configure examples file name with the getExampleFilename option.

If you need to display some JavaScript code in your documentation that you don’t want to be rendered as an interactive playground you can use the static modifier with a language tag (e.g. js static).

External examples using doclet tags#

Additional example files can be associated with components using @example doclet syntax.

The following component will also have an example loaded from the extra.examples.md file:

* Component is described here.
* @example./extra.examples.md
exportdefaultclassButtonextendsReact.Component{
}

You’ll need a regular example file (like Readme.md) too when skipComponentsWithoutExample is true.

Public methods#

By default, any methods your components have are considered to be private and are not published. Mark your public methods with JSDoc @public tag to get them published in the docs:

* Insert text at cursor position.
* @param{string}text
*/
// ...

Ignoring props#

By default, all props your components have are considered to be public and are published. In some rare cases, you might want to remove a prop from the documentation while keeping it in the code. To do so, mark the prop with JSDoc @ignore tag to remove it from the docs:

/**
* A prop that should not be visible in the documentation.
* @ignore
hiddenProp:React.PropTypes.string

Defining custom component names#

Use @visibleName JSDoc tag to define component names that are used in the Styleguidist UI:

* The only true button.
* @visibleName The Best Button Ever 🐙
classButtonextendsReact.Component{

The component will be displayed with a custom “The Best Button Ever 🐙” name and this will not change the name of the component used in the code of your app or Styleguidist examples.

Using JSDoc tags#

You can use the following JSDoc tags when documenting components, props and methods:

When documenting props you can also use:

All tags can render Markdown.

* The only true button.
* @version 1.0.1
* @author [Artem Sapegin](https://github.com/sapegin)
* @author [Andy Krings-Stern](https://github.com/ankri)
classButtonextendsReact.Component{
/**
*/
/**
*
* @see See [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names) for a list of color names
* @see See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) for a list of color names
color:PropTypes.string,
* The size of the Button
* @since Version 1.0.1
size:PropTypes.oneOf(['small','normal','large']),
* The width of the button
* @deprecated Do not use! Use `size` instead!
width:PropTypes.number,
* Gets called when the user clicks on the button
* @param{SyntheticEvent}event The react `SyntheticEvent`
* @param{Object}allProps All props of this Button
onClick:PropTypes.func
}

Writing code examples#

Code examples in Markdown use ES6+JSX syntax. You can use the current component without explicitly importing it:

Jsdoc markdown link
<Button>Push Me</Button>

Styleguidist uses Bublé to run ES6 code on the frontend, it supports most of the ES6 features.

To use other components, you need to explicitly import them:

import Button from'../Button'
<p>
Using the Button component in the example of the Panel component:
<Button>Push Me</Button>

You can also import other modules, like mock data:

import mockData from'./mocks'

Or you can explicitly import all your example dependencies, to make examples easier to copy into your app code:

import React from'react'
import Placeholder from'rsg-example/components/Placeholder'

rsg-example module is an alias defined by the moduleAliases config option.

Jsdoc

You can only use import by editing your Markdown files, not by editing the example code in the browser.

Jsdoc-to-markdown Multiple Files

Each example acts as a function component and you can use the useState Hook to handle its state.

const[isOpen, setIsOpen]= React.useState(false)
<buttononClick={()=>setIsOpen(true)}>Open</button>
Markdown
<h1>Hallo!</h1>
<buttononClick={()=>setIsOpen(false)}>Close</button>

Jsdoc Markdown Template

</div>

Vscode Jsdoc Markdown

If a component uses React Context, you need a context provider in the example or in a custom Wrapper component. See ThemeButton example.

If you need a more complex demo it’s often a good idea to define it in a separate JavaScript file and import it in Markdown.

Limitations#

Jsdoc-to-markdown Typescript

In some cases Styleguidist may not understand your components, see possible solutions.