Add documentation to the typings

[Thiht]

Hi!
I'm using the router and as a new user I feel like I'm wasting tons of time constantly switching between my code/the typings, and the documentation. For example, I'm writing the following:

<Link
  to={"/timelines/$timelineId/history"}
  params={{ timelineId: id }}
  className="[&.active]:font-bold"
  activeOptions={{
    // I'm here
  }}
>
  {name}
</Link>

and when I cmd+click to see what's available in activeOptions, all I have is:

export interface ActiveOptions {
    exact?: boolean;
    includeHash?: boolean;
    includeSearch?: boolean;
    explicitUndefined?: boolean;
}

While it's better than nothing, I have to switch to the documentation for ActiveOptions (this one, not this one that's the first match) to find a documented version of the type:

export interface ActiveOptions {
  // If true, the link will be active if the current route matches the `to` route path exactly (no children routes)
  // Defaults to `false`
  exact?: boolean
  // If true, the link will only be active if the current URL hash matches the `hash` prop
  // Defaults to `false`
  includeHash?: boolean // Defaults to false
  // If true, the link will only be active if the current URL search params inclusively match the `search` prop
  // Defaults to `true`
  includeSearch?: boolean
  // This modifies the `includeSearch` behavior.
  // If true,  properties in `search` that are explicitly `undefined` must NOT be present in the current URL search params for the link to be active.
  // defaults to `false`
  explicitUndefined?: boolean
}

Could this annotated version be embedded directly in the typings? This would really make working with the router easier and save tons of time. (Obviously ActiveOptions is just an example, I would like this change for all the interfaces)

Or as an alternative, could the type be annotated with a direct link to the corresponding documentation?

edit: just noticed it's already talked about in the v2 discussion:

JSDoc Annotations

• Add inline JSDoc annotations to most of the API to help with IDE documentation
• Potentially auto-generate API reference documentation

Guess I didn't use the right keywords when searching if it was already suggested!

[schiller-manuel]

yes this is definitely a good idea. we have done so for other types already (description and link to the docs)
feel free to create a PR so we get there sooner

[Thiht]

Cool that's good to know!
If I contribute, do I just need to add the comments on the types? Nothing special to do to make sure they appear in the dist bundle?
Is it ok to copy paste from the docs or do you already have tooling to prevent duplication? (ie. include the actual types in the docs by import, something like that)

[schiller-manuel]

copying from the docs is actually what we want here because ultimately we want to generate docs from the code automatically.
no need to do anything special I guess for the dist types, let's find out

[RMHonor]

I started adding JSDoc comments to route generator plugin, but realised anything using Zod schemas won't work. The z.infer utility type strips away any JSDoc comments despite them appearing on the generated schema types (issue).

One solution is to create an interface with all the docs on, and make sure the schema satisfies this type. This creates some duplication, and moves Zod to just being a runtime validation library. Example:

export interface Config {
  /**
   * The framework of your application, either `react` or `solid`.
   *
   * @default 'react'
   */
  target?: 'react' | 'solid';
}

export const configSchema = z.object({
  target: z.enum(['react', 'solid']).optional().default('react'),
}) satisfies z.ZodType<Config>;

Any other thoughts?

[RMHonor]

As an aside, we should switch to z.input anyway, z.infer uses the output type, not input, which is why there's use of Partial<Config> everywhere. (docs)