Documentation: development guidelines

[marcelovicentegc]

The goal of this PR is to create an internal documentation regarding how developers should document components and methods from any of our packages.

It's a complementary action that follows up on:

• feat: docs generator #1290

And which end goal is to make sure that our docs remain concise and with plenty of examples, culminating on the implementation of linting rules for our guidelines, as described in:

• TypeDoc lint tool #1371

A couple of guideline examples

• We must make sure to document components and each of their props correctly, preferentially following the pattern of a component that is already well documented, such as the Button.
• Let's make the best usage from typedoc tags (https://typedoc.org/guides/tags/).
• All @example tags are used to generate a playground, so let's be careful with its usage, which should be documented somewhere and possibly have linting rules setup for typedocs.

Good documentation example

/**
 * Buttons triggers allow users to identify and start the most important actions in a container.
 *
 * @example
 * <Button>Action label</Button>
 */
export function Button(props: ButtonProps) {
    const {
        children,
        size = 'normal',
        variant = 'secondary',
        ...rest
    } = props

    return <button data-size={size} data-variant={variant} {...rest}>{children}</button>
}

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
    /**
     * The size of the button.
     *
     * @default 'normal'
     */
    size?: 'small' | 'normal' | 'large'
    /**
     * The variant of the button.
     *
     * @default 'secondary'
     */
    variant?: 'primary' | 'secondary' | 'tertiary'
}

[beatrizmilhomem]

Has the InnerSource engineering documentation already addressed this?