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:
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:
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.
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'
}
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:
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:
A couple of guideline examples
@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