@apptension/react-comment-docs

react-comment-docs

Low-effort self-documented components.

This small package allow you to create documentation for your components on the fly. It's as simple as writing comments in your files. It will create a markdown file for each of your components automatically! You can customize it however you want in config.js. For even better experience, we recommend using our snippets for VSCode.

Getting started

Install npm package ✨

npm i --save-dev @apptension/react-comment-docs

Run watcher 👀

npx @apptension/react-comment-docs

How to use it?

Syntax:

// @docs {field}
-> code here
// !docs {field}

Component description

// @docs description
 This is example component description. Keep it simple and easy to understand, try to describe all the component logic. 
// !docs description

Component props

// @docs props
props = { 
  text,
  props2,
  props3,
}
// @
function ExampleComponent(props) {
  return ()
}

Component functions

  // @docs functions
  const getNameLength = (name) => {
    return name.length;

  function getNameType(name){
    return typeof(name)  
  }
  // !docs functions

DOM elements

function ExampleComponent(props) {
  return (
    // @docs DOM
    <div>
        <p>Lorem ipsum</p>
    </div>
    // !docs DOM
  )
}

PropTypes

// @docs propTypes
ExampleComponent.propTypes = {
  name: PropTypes.string.isRequired,
  darkMode: PropTypes.bool,
};
// !docs propTypes

Translations

// @docs translations
<CustomButton
 label={intl.formatMessage({
    description: 'A11Y: Navigation Button',
    defaultMessage: 'Navigate',
  })}
 />
// !docs translations

Config

Config file is placed in node_modules/@apptension/react-comment-docs. You can specify the fields used in your docs, allowed component extensions, components and templates directory.

export const config = {
  fields: ["name", "description", "functions", "DOM", "props", "translation"],
  templatePath: "./template.md",
  dynamicTemplatePath: "./dynamic-template-fragment.md",
  extensions: [".js", ".jsx", ".ts", ".tsx"],
  componentsDir: "./components",
};

Custom docs fields

You can specify your own fields by adding them in config.js file and use it in your components;

export const config = {
  fields: ["your-field"],
};

// @docs your-field

 const example = some.important.code.to.document();

// !docs your-field

Add component snippets with docs included in VSCODE

1. Copy the code from SNIPPETS.json file
2. Open VSCode console using cmd + P then type and select >Configure User Snippets
3. Select javascriptreact.json file.
4. Paste the code from SNIPPETS.json file