Documentation Guidelines

The Documentation Guidelines outline important rules and recommendations for creating clear and concise technical documentation. These guidelines should be followed when writing documentation for our website, JSDocs, and any other text intended for our users.

General Documentation Guidelines

We recommend following the rules below:

1. Always use Present Simple and Active Voice.

   Do --- "Name the following property as described below..."
   Don't --- "The property should be named..."

   Do --- An anchor component wraps anything that will have the link behavior.
   Don't  --- An anchor component is used to wrap anything that will have the link behavior.

2. Avoid Passive Voice if possible. If you don't know how to describe something in Active Voice, use the Passive Voice.

   "When a component acts as a dropdown, it indicates that the dropdown is opened."

3. Avoid broken English phrases, hard to understand, overcomplicated and long sentences. It's better to break down one long sentence into to 2-3 short ones.

   Do --- "Screens that would otherwise be empty can be populated with starter content to help newcomers. Starter content allows new users to begin using a website immediately, making it easier for them to learn about what a website offers."
   Don't --- "To help users new to a website or section, screens that would otherwise be empty can be populated with starter content. Starter content allows users to begin using a website immediately, making it easier for them to learn about what a website offers."

   Do --- "Try to avoid this type of empty state. If there is not enough space for an image, use text only."
   Don't --- "Try to avoid this type of empty state, but use only text in places where there is not enough space for an image."

   Do --- "This approach may serve everyone."
   Don't --- "This approach is reusable for everyone."

   Do --- "When the next update is available, Sketch notifies you with a "Library Updates Available" message in the top right corner."
   Don't --- "When the next update is available, Sketch notifies you by following the message "Library Updates Available" in the top right corner."

4. Default Style Guides:

   Google Developer Documentation(https://developers.google.com/style)

   MS Style Guide(https://learn.microsoft.com/en-us/style-guide/welcome/)

API design and documentation guidelines

General rules:

1. We prioritize careful consideration when naming props and API, as changing them later can be difficult and result in breaking changes. Therefore, it is essential to think twice when choosing names.
2. JSDoc documentation of new API and prop should be added immediately.

Guidelines for different type of prop

Below we provide documentation patterns and description for various type of props.

Please note, that patterns based on general cases, you can add more specific information and details if needed.

Callbacks

• Event handlers – onClick, onFocus. Start with ‘on’.

• Render callbacks – renderItem, renderFooter. Start with ‘render’.

• Pure function callbacks – getName, getRowOptions. Starts from 'get' or 'is'.

Event handlers

Event handler is a function that is executed in response to a specific event occurring. It is typically used to define the behavior or actions to be performed when the event is triggered.

Event handlers props should tart with 'on'. Often receive 'event' as a param and return void.

API documentation pattern:

/** Called when [event description]. */

Examples:

/** Called when component is clicked */
onClick?(e?: MouseEventHandler<T>): void;

/** Called when value needs to be changed (usually due to user interaction) */
onValueChange(newValue: T): void;

/** Called when accept icon is clicked 
 * If provided, enables accept (check) icon.
 */
onAccept?(): void;

Render Callbacks

Render callback props accept a function that renders a component part. These props should start with 'render'. Function should return React.ReactNode.

API documentation pattern:

/** Render callback for [description of which part will be rendered]. 
 * 
 * [optional additional info - use cases, details]
 * 
 * [if component renders something by default]
 * If omitted, [component name or description of what will be rendered] will be rendered.
 * 
 * [if nothing is rendered by default]
 * If omitted, no [component part] will be rendered.
 */

Examples:

/** 
 * Render Callback for each picker row.
 * Can be used to add subtitles, avatars, etc. [link to example]
 * If omitted, DataTableRow will be rendered.
*/
renderRow?: (props: DataRowProps<TItem, TId>) => ReactNode;

/** 
 * Render Callback for the footer below the calendar. 
 * If omitted, no footer will be rendered.
 */
renderFooter?(): ReactNode;

Pure function callbacks

These props usually start with ‘get’ or ‘is’ and are expected to return some value.

Examples: getId, getParentId, getName, getRowOptions, isFoldedByDefault. These props access a function to get or compute some based on some parameters.

These functions are expected to be pure:

• The function's return value on the function call should only depend on the input function arguments.
• It should not modify any non-local state. It means the function should not manipulate anything other than the data stored in the local variables declared within it.
• The function should not have any side effects, such as reassigning non-local variables, mutating the state of any part of code that is not inside the function or calling any non-pure functions inside it.

API documentation pattern:

/**
 * A pure function that gets [something] [from|for|given|of] [something].
 * 
 * [Additional info - use cases, details]
 * 
 * [If there's a default behavior:]
 * If omitted, [default behavior]
 */

Examples:

/** A pure function that gets entity name from entity object.
 *  Default: (item) => item.name. 
 */
getName?: (item: TItem) => string;

/** A pure function that gets options for each row. 
 * Allow to make rows non-selectable, as well as many other tweaks. 
 */
getRowOptions?: (item: TItem, index: number) => DataRowOptions<TItem, TId>;

/**
 * A pure function that gets the initial folding state of a row.
 * Can be used to unfold all or some items at the start.
 * If omitted, all rows would be folded.
 */
isFoldedByDefault?(item: TItem): boolean;

Scalars

Scalar values are simple, primitive data types that represent single values, e.g.: Strings, Numbers, Booleans and etc.

Booleans

These props usually start with ‘is’ and allow you to toggle certain features or apply visual changes to the component based on their values(true/false).

Booleans

API documentation pattern:

/**
 * Pass true to [describe behavior when true].
 * [If not 100% clear:] If false, [describe behavior when false]

 * If omitted, [default behavior]
*/

In cases, when prop not defined by user, but calculated by us and indicate something:

/** Indicates [describe what indicate] */

Examples:

/** Pass true to disable editing, and visually de-emphasize value of the component */
isDisabled?: boolean;

/** Pass true to disable editing. Unlike isDisabled, keep component's value readable. */
isReadonly?: boolean;

/** Pass true to mark component as required */
isRequired?: boolean;

/** Pass true to indicate that dropdown is open, in case when component acts as dropdown. */
isOpen?: boolean;

/** Indicated that component act as dropdown */
isDropdown?: boolean;

/** Indicates that dropdown is open */
isOpen?: boolean;

Code docs - checklist

• Added general description by patterns bellow.
• Default behavior described. E.g. 'If ommitted, ...'
• Provide example on when this property can be useful, if it's not 100% clear. E.g. Can be used to add subtitles, avatars, etc. [link to example]
• Is there are good documentation to put link to? Either at UUI site, or some external. E.g. Flexbox flex-grow property [Flexbox Guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-flex-grow)
• Is there are some non-obvious behavior, like special values, or relation to other props?