Fluentui: Better documentation for ICommandBarItemProps

[sliminality]

I hope this is the right place to file documentation issues -- if not, let me know and I'd be happy to edit this issue to follow the bug report template.

The documentation for <CommandBar> is rather opaque regarding the structure of ICommandBarItemProps. Since the items list is arguably the most important part of the <CommandBar> API, improving this documentation would be a big DX win.

Examples

Currently, neither of the examples describe how the items array should be structured. Instead, they are thin wrappers around the <CommandBar> component. The first example in particular is practically the identity component:

public render(): JSX.Element {
    const { items, overflowItems, farItems } = this.props;

    return (
      <div>
        <CommandBar
          items={items}
          overflowItems={overflowItems}
          farItems={farItems}
          ariaLabel={'Use left and right arrow keys to navigate between commands'}
        />
      </div>
    );
  }

The second example, "CommandBar custom buttons and overflow menu," is also unclear because:

• Both examples include an overflow menu, and the difference between the two (the second example includes a caret) is extremely subtle, and
• The custom button functionality consists of logging $ITEM_NAME hovered whenever the user mouses over a button. This behavior is invisible, unless the user happens to have the console open.

Suggested changes:

• Both examples should include at least the items prop as a full array/object literal.
• In the first example, the unused component state should either be removed or used somewhere.
• In the second example, the custom button functionality should exhibit a more obvious behavior, such as displaying an alert() dialog.
• The examples should be renamed to clarify the difference between their overflow menus: e.g. "overflow menu" and "overflow menu with caret."

API documentation

After reading the examples, I was still unsure how to actually use the <CommandBar>, so I looked at the documentation. Sure enough, the first required prop was items: ICommandBarItemProps[].

However, the interface table for ICommandBarItemProps only lists six optional members. It's never actually stated that ICommandBarItemProps inherits from IContextualMenuItem, which is documented much further down the page with no context, despite being one of the most important <CommandBar> APIs. I had to grep the source to figure out the relationship.

Suggested changes:

• Next to the "ICommandBarItemProps interface" header, provide some indication of inheritance, along with a link to the "IContextualMenuItem interface" section. At the very least, searching the page for "IContextualMenuItem" should give some kind of context or inbound pointer -- currently, it's unclear why that API is listed at all.
• Even better, inherited members could be inlined directly into the ICommandBarItemProps table. If inlining would be unfaithful to the object-oriented paradigm, then the two sections should appear back-to-back for ease of use.

[JasonGore]

The parser automatically generates this documentation from each component's types.ts file and shows types in the order they are defined. However, it does not seem to expand or document interface inheritance, which is why that detail is not shown.

I see this issue having two parts:

1. Refine CommandBar examples based on the feedback written
2. Modify parser to shown inheritance information (ideally with a link to the interface being extended or consider other options such as shown inherited members in italics)

Similar to #5937, if you'd like to submit a PR for any of these, it'd be more than welcome. Thanks!

[micahgodbolt]

• [x] Put items into the code rather than in external file
• [x] Make custom button functionality more visible (change to alert)
• [x] Make 2nd example changes less subtle
• [x] Remove unnecessary state
• [x] Add reference to IContextualMenuItem

[micahgodbolt]

Opened up a separate issue to capture the work needed for improved implementation section #6015. Will close this issue up with specific work to clarify CommandBar examples and interface comments.