vtex / shoreline

VTEX Design System for back-office experiences. Currently available for internal usage at VTEX.
https://shoreline.vtex.com
18 stars 1 forks source link

Documentation: development guidelines #1305

Closed marcelovicentegc closed 1 month ago

marcelovicentegc commented 8 months ago

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:

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

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 commented 1 month ago

Has the InnerSource engineering documentation already addressed this?