react-docgen-typescript: Union types cannot be documented

I ran into an issue earlier where union types caused the all of the props of a component not to be documented (the props names appeared in the documentation, but none of their descriptions, etc). I have removed my unions, but it’s not the best solution.

There are cases where this is useful, when one prop should only be provided if another is present, and must be provided if another is present e.g.

interface FixedWidth {
  fixWidth: true;
  width: number;
}

interface FlexibleWidth {
  fixWidth?: false;
  width?: never;
}

type Props = FixedWidth | FlexibleWidth;

About this issue

Original URL
State: closed
Created 6 years ago
Reactions: 7
Comments: 15 (10 by maintainers)

Most upvoted comments

Hi, anyone was able to solve this somehow?

dwojtyca on Jun 19, 2018

I just started work on a react typescript project and was looking at using styleguidist. I have some slightly more-complex types and was wondering how this would even begin to work, it seems like an incredibly difficult task. To give an example, how would something like this contrived example be documented:

interface IBasicComponentProps {
  // ...
};

interface ITypeAComponentProps {
  isTypeA: boolean;
  // ...
};

interface ITypeBComponentProps {
  isTypeB: boolean;
  // ...
};

interface ITypeCComponentProps {
  isTypeC: boolean;
  // ...
};

type ComponentProps =
  | IBasicComponentProps
  | ITypeAComponentProps
  | ITypeBComponentProps
  | ITypeCComponentProps;

I think the easiest way to deal with something like this is to be able to be able to write documentation somewhere (e.g. the top of the file?) that overrides the parsing of the types for that file and uses that documentation instead.

As an aside, if the process for converting types to docs was reversible, you could even check that the overridden documentation satisfies the actual type used for the props of a given component.

I’m totally spitballing here since I’m only getting introduced to styleguidist now for the first time so I have no idea if this actually a legitimate suggestion.

petejodo on May 11, 2018

But how should it work? Which description should take precedence over which? Should they be merged as it is when you use type intersection?

Havret on Jan 22, 2018