API documentation

[stevenpetryk]

• [ ] Add TSDoc comments to all components and props
• [ ] Spit out some kind of documentation to embed on the website, perhaps a Gatsby plugin can help out here

[stevenpetryk]

Still super unsure how to do this in these TypeScripty times. API Extractor seems like a neat tool, but it does SO MUCH STUFF and always seems to spit out some errors at me. I might try moving the build system from the custom webpack config it currently has, to something like tsdx, esbuild, or whatever.

Too many options.

Life is so short.

[stevenpetryk]

Today I moved the build pipeline to esbuild, and got api-extractor integrated. Should be easy enough to turn its API report into docs.

[stevenpetryk]

^ famous last words

There is still surprisingly not much in this space! There's react-docgen-typescript, but from my experience tweaking that for Storybook at Discord, I'd rather not use it. API Extractor seems to break now that I'm using Node 16/pnpm/the latest TypeScript (I have no idea why it's breaking).

I like Radix's docs, but they hand-write every prop table. I don't have the time for that, nor the discipline to keep it up-to-date.

[amanape]

After reviewing the documentation provided by Radix, I am prepared to begin manually implementing the API for the table component. The main task will involve passing data props to the component. e.g.:

interface Prop {
  label: string;
  info: string;
  required: boolean;
}

interface PropType {
  label: 'string' | 'boolean' | 'enum' | 'function'; // This can be made a more dynamic type if required
  info?: string;
}

type PropDefault = string;

interface TableRow {
  prop: Prop;
  type: PropType;
  default?: PropDefault;
}

I anticipate that the main challenge will be finding and learning the API on my own in order to document it. If there is any existing documentation that could assist with this task, please let me know.

[stevenpetryk]

@amanape to clarify what I said in the previous comment, I don't think it's sustainable for anyone to manually keep prop tables up to date (not just me). They should be autogenerated from type analysis. Even though it's not the greatest tool I feel like react-docgen-typescript will be the only way.