How to document components

How to document components

As we are creating more and more components I'm documenting some practices which are necessary regarding the quality of code documentation.

Every production ready component must been documented. For this case we already introduced the valid-jsdocs and require-jsdoc ESLint rules to force every developer to document their javascript code. Generally, there are not many things to consider when documenting our components.

Document your properties

As we are developing UI components it is necessary to document the properties. Below is an example how you can document your React components props in a proper way so they are later visualised in the API Markdown documentation.

/**
 * The default Header to be used everywhere
 * @class WSHeader
 * @extends Component
 * @property {object} props             - properties
 * @property {function} props.setLang   - handler which sets language
 * @property {function} props.setLogin  - handler which sets Login information (token and boolan for loggedin)
 * @property {number} props.clientId    - clientId
 * @property {string} props.redirectUrl - URL to redirect after successfully login
 * @property {string} props.logoUrl     - url for logo
 * @property {string} props.title       - title of Header
 * @property {array} props.links        - List of navigation links based on object format {label, value, onclick-Handler }
 *
 */

This jsdocs documentation of our WSHeader component will be transformed into an enhanced markdown list representation. So it is also recommended that you add the correct types of your props object. It will result into this auto-generated Markdown:

Properties

• props object properties
  • props.setLang function handler which sets language
  • props.setLogin function handler which sets Login information (token and boolan for loggedin)
  • props.clientId number clientId
  • props.redirectUrl string URL to redirect after successfully login
  • props.logoUrl string url for logo
  • props.title string title of Header
  • props.links array List of navigation links based on object format {label, value, onclick-Handler }

As you can see using jsdocs + documentationjs allows us to create a nice looking, easy to read markdown representation which will be helpful when other developers want to use a component.

Adding component to the index

Currently, there is no automatic process which reads through all components in the src-folder and adds them to the index.md. Therefore whenever you add your final component to the index.js-file you also have to add a @link property to your component with a relative path:

/**
 * Our Wholesale-Styleguide Component documentation
 * This is our Startpage for our component API
 * based on jsDocs
 * Here we should add more descriptions
 * Below are all components referenced
 *
 * - See {@link ws-header/ws-header.md|WSHeader}
 * - See {@link ws-date-picker/ws-date-picker.md|WSDatePicker}
 * - See {@link ws-dropdown/ws-dropdown.md|WSDropdown}
 * - See {@link ws-notification/ws-notification|WSNotification}
 * @module WHStyleguide
 */

export {WSHeader} from './ws-header/ws-header';
export {WSDatePicker} from './ws-date-picker/ws-date-picker';
export {WSDropdown} from './ws-dropdown/ws-dropdown';
export {WSNotification} from './ws-notification/ws-notification';

This documentation will be later transformed into the index.md File as the entry-point.

Additional reads

• JsDocs
• Documentationjs