Union types cannot be documented

[JakeSidSmith]

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;

[Havret]

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

[JakeSidSmith]

I guess I'd treat them as if they were intersections and follow the same rules. 🙂

[pvasek]

I think this is similar to #56. I guess the proper solution would be somehow integrate styleguidist with typedoc (https://github.com/TypeStrong/typedoc) or something similar. But then it seems more like question to @sapegin. Should I create issue for that question in styleguidist repo?

[petejodo]

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.

[dwojtyca]

Hi, anyone was able to solve this somehow?

[JakeSidSmith]

I've just removed my union types and manually documented that certain props are required when others are supplied. Not ideal, but we're using this for an internal tool, so it's not a big deal.

[hipstersmoothie]

I would like to give a shot at doing thing. My codebase has started to support unions more and more and this would be a killer feature.

As to what it should look like

/* A version of the component where the width is required */
interface FixedWidth {
  /* The width is fixed and is required */
  fixWidth: true;
  /* The width of the component */
  width: number;
}

/* A version of the component where the width is not required */
interface FlexibleWidth {
  /* The width is not fixed and is not required */
  fixWidth?: false;
  /* The width if needed */
  width?: never;
}

type Props = FixedWidth | FlexibleWidth;

/* My component that uses Union */
export const Component: React.FC<Props> = () => {}

Should produce:

---

Component

My component that uses Union.

Component - FixedWidth

A version of the component where the width is required.

Name	Type	Default	Description
fixWidth	true		The width is fixed and is required
width	number		The width of the component

Component - FlexibleWidth

A version of the component where the width is not required.

Name	Type	Default	Description
fixWidth	false		The width is not fixed and is not required
width	never		The width if needed

[hipstersmoothie]

@JakeSidSmith @pvasek @Havret does this seem reasonable?

[JakeSidSmith]

Almost, but you've used never in flexible, and it renders number in the docs?

Should width be omitted from the flexible interface?

[hipstersmoothie]

Almost, but you've used never in flexible, and it renders number in the docs?

typo! correctd

[hipstersmoothie]

Should width be omitted from the flexible interface?

I think if should be included. Maybe we could include a config option to exclude it though.

Does it ever make sense to include a never?

[JakeSidSmith]

Does it ever make sense to include a never?

That is something I'm still unsure about. I guess in some circumstances you may explicitly want someone to never supply that prop. 🤷‍♂

[hipstersmoothie]

My proposal above would be a breaking change and make this project incompatible with most libraries. After #247 is merged the union/intersection types should use the merged types. I don't think it can get much better without a breaking change