fix descriptions for customizable components (#518)

Author: chrismohr

config/yo/generator-component/app/templates/Component.tsx

@@ -6,10 +6,7 @@ import { join } from '../../util/classNames';
 import { <%= name %>Props, <%= name %>Type } from './<%= name %>.types';
 import { getClassNames } from './<%= name %>.styles';
 
-/**
- * Describe what `<%= name %>` does. This will also appear as part of this component's
- * documentation.
- */
+
 export class <%= name %> extends React.Component<<%= name %>Props & CustomizableComponentProps> {
   public render() {
     const { className, type = <%= name %>Type.BLACK, theme = defaultTheme } = this.props;
@@ -23,5 +20,9 @@ export class <%= name %> extends React.Component<<%= name %>Props & Customizable
   }
 }
 
+/**
+ * Describe what `<%= name %>` does. This will also appear as part of this component's
+ * documentation.
+ */
 @customizable('<%= name %>', ['theme'])
 export default class Customizable<%= name %> extends <%= name %> {}

package-lock.json

@@ -57,7 +57,7 @@
     "raw-loader": "0.5.1",
     "react": "16.3.2",
     "react-docgen": "2.21.0",
-    "react-docgen-typescript": "1.6.1",
+    "react-docgen-typescript": "1.7.0",
     "react-dom": "16.3.2",
     "react-styleguidist": "7.0.20",
     "react-styleguidist-visual": "0.8.0",

package.json

@@ -9,9 +9,6 @@ import { AsideSectionProps } from './AsideSection.types';
 import Text, { TextSize } from '../Text';
 import { getClassNames } from './AsideSection.styles';
 
-/**
- * A section component to be used primarily for sidebar modules
- */
 export class AsideSection extends React.Component<AsideSectionProps & CustomizableComponentProps> {
   public render() {
     const { title, children, theme = defaultTheme } = this.props;
@@ -47,5 +44,8 @@ export class AsideSection extends React.Component<AsideSectionProps & Customizab
   }
 }
 
+/**
+ * A section component to be used primarily for sidebar modules
+ */
 @customizable('AsideSection', ['theme'])
 export default class CustomizableAsideSection extends AsideSection {}

src/components/AsideSection/AsideSection.tsx

@@ -51,5 +51,8 @@ export class Avatar extends React.Component<AvatarProps & CustomizableComponentP
   }
 }
 
+/**
+ * An `Avatar` shows a thumbnail representation of both an individual or group.
+ */
 @customizable('Avatar', ['theme'])
 export default class CustomizableAvatar extends Avatar {}

src/components/Avatar/Avatar.tsx

@@ -6,12 +6,6 @@ import { getClassNames } from './Block.styles';
 import { BlockProps } from './Block.types';
 import { CustomizableComponentProps, defaultTheme, customizable } from '../Customizer';
 
-/**
- * A `Block` is a layout component to build consistent padding and vertical spacing between
- * components. It allows you to `push` a chunk of UI up or down by individual pixels to keep text in
- * the `4px` vertical rhythm. It's also the primary place you should set `textSize` in your UIs,
- * providing enumerated options for the supported `font-size`/`line-height` combinations.
- */
 export class Block extends React.Component<BlockProps & CustomizableComponentProps> {
   public render() {
     const { children, textSize, className, theme = defaultTheme, ...remainingProps } = this.props;
@@ -26,5 +20,11 @@ export class Block extends React.Component<BlockProps & CustomizableComponentPro
   }
 }
 
+/**
+ * A `Block` is a layout component to build consistent padding and vertical spacing between
+ * components. It allows you to `push` a chunk of UI up or down by individual pixels to keep text in
+ * the `4px` vertical rhythm. It's also the primary place you should set `textSize` in your UIs,
+ * providing enumerated options for the supported `font-size`/`line-height` combinations.
+ */
 @customizable('Block', ['theme'])
 export default class CustomizableBlock extends Block {}

src/components/Block/Block.tsx

@@ -7,10 +7,6 @@ import { join } from '../../util/classNames';
 import { getClassNames } from './Box.styles';
 import { BoxProps } from './Box.types';
 
-/**
- * A Box is a div with a border and fixed padding. It also has `display: relative` so you can
- * absolutely-position elements like a close button. Boxes will primarily be used for card views.
- */
 export class Box extends React.Component<BoxProps & CustomizableComponentProps> {
   public render() {
     const { children, onClick, className, backgroundColor, borderColor, theme = defaultTheme } = this.props;
@@ -27,5 +23,9 @@ export class Box extends React.Component<BoxProps & CustomizableComponentProps>
   }
 }
 
+/**
+ * A Box is a div with a border and fixed padding. It also has `display: relative` so you can
+ * absolutely-position elements like a close button. Boxes will primarily be used for card views.
+ */
 @customizable('Box', ['theme'])
 export default class CustomizableBox extends Box {}

src/components/Box/Box.tsx

@@ -19,9 +19,6 @@ import {
 
 const hrefBlacklist = ['', '#', 'javascript://'];
 
-/**
- * A `Button` allows a user to take an action.
- */
 export class Button extends React.Component<ButtonProps & CustomizableComponentProps> {
   public static propTypes = {
     // TypeScript does not support negated types, so we need to do a runtime validation instead.
@@ -116,5 +113,8 @@ export class Button extends React.Component<ButtonProps & CustomizableComponentP
   }
 }
 
+/**
+ * A `Button` allows a user to take an action.
+ */
 @customizable('Button', ['theme'])
 export default class CustomizableButton extends Button {}

src/components/Button/Button.tsx

@@ -7,11 +7,6 @@ import { join } from '../../util/classNames';
 import { getClassNames } from './Clickable.styles';
 import { ClickableProps } from './Clickable.types';
 
-/**
- * A `Clickable` is an accessible, clickable area that accepts arbitrary children. It is styled
- * like a link by default, but can also be unstyled. Under the hood `Clickable` simply wraps
- * content in a `button` element.
- */
 export class Clickable extends React.Component<ClickableProps & CustomizableComponentProps> {
   private buttonRef = React.createRef<HTMLButtonElement>();
 
@@ -48,5 +43,10 @@ export class Clickable extends React.Component<ClickableProps & CustomizableComp
   }
 }
 
+/**
+ * A `Clickable` is an accessible, clickable area that accepts arbitrary children. It is styled
+ * like a link by default, but can also be unstyled. Under the hood `Clickable` simply wraps
+ * content in a `button` element.
+ */
 @customizable('Clickable', ['theme'])
 export default class CustomizableClickable extends Clickable {}

src/components/Clickable/Clickable.tsx

@@ -11,9 +11,6 @@ import { KeyCodes } from '../../util/keyCodes';
 import { getClassNames } from './EditableText.styles';
 import { EditableTextProps, EditableTextState } from './EditableText.types';
 
-/**
- * Displays text which can be edited on click.
- */
 export class EditableText extends React.Component<EditableTextProps & CustomizableComponentProps, EditableTextState> {
   private textFieldFocusable: Focusable | null;
   private clickableFocusable: Focusable | null;
@@ -140,5 +137,8 @@ export class EditableText extends React.Component<EditableTextProps & Customizab
   };
 }
 
+/**
+ * Displays text which can be edited on click.
+ */
 @customizable('EditableText', ['theme'])
 export default class CustomizableEditableText extends EditableText {}

src/components/EditableText/EditableText.tsx

@@ -6,14 +6,6 @@ import { FakeLinkProps } from './FakeLink.types';
 import { getClassNames } from '../FakeLink/FakeLink.styles';
 import { CustomizableComponentProps, defaultTheme, customizable } from '../Customizer';
 
-/**
- * A `FakeLink` is simply a span which imitates the styling of an `<a>` tag (or `NavigationLink`
- * component). It is meant to be nested within unstyled `NavigationLink` or `Clickable`
- * components, allowing an entire block of content to be an accessible tabbable element while
- * still showing individual nested "links" for sighted users.
- *
- * NOTE: If you are looking for click interaction please see [Clickable](#clickable).
- */
 export class FakeLink extends React.Component<FakeLinkProps & CustomizableComponentProps> {
   public render() {
     const { className, children, theme = defaultTheme } = this.props;
@@ -23,5 +15,13 @@ export class FakeLink extends React.Component<FakeLinkProps & CustomizableCompon
   }
 }
 
+/**
+ * A `FakeLink` is simply a span which imitates the styling of an `<a>` tag (or `NavigationLink`
+ * component). It is meant to be nested within unstyled `NavigationLink` or `Clickable`
+ * components, allowing an entire block of content to be an accessible tabbable element while
+ * still showing individual nested "links" for sighted users.
+ *
+ * NOTE: If you are looking for click interaction please see [Clickable](#clickable).
+ */
 @customizable('FakeLink', ['theme'])
 export default class CustomizableFakeLink extends FakeLink {}

src/components/FakeLink/FakeLink.tsx

@@ -12,11 +12,6 @@ import { HovercardProps, HovercardState, TriggerType } from './Hovercard.types';
 const hideDelay = 500;
 const showDelay = 750;
 
-/**
- * A `Hovercard` is a small popover overlay. It opens on click or
- * mouse enter, and closes on mouse out and `ESC`. It should be used with `HovercardHeader` and
- * `HovercardBody` components for consistent internal padding.
- */
 export class Hovercard extends React.Component<HovercardProps & CustomizableComponentProps, HovercardState> {
   public static defaultProps: Partial<HovercardProps> = {
     directionalHint: DirectionalHint.bottomCenter,
@@ -203,5 +198,10 @@ export class Hovercard extends React.Component<HovercardProps & CustomizableComp
   };
 }
 
+/**
+ * A `Hovercard` is a small popover overlay. It opens on click or
+ * mouse enter, and closes on mouse out and `ESC`. It should be used with `HovercardHeader` and
+ * `HovercardBody` components for consistent internal padding.
+ */
 @customizable('Hovercard', ['theme'])
 export default class CustomizableHovercard extends Hovercard {}

src/components/Hovercard/Hovercard.tsx

@@ -7,9 +7,6 @@ import Block, { GutterSize } from '../Block';
 import { getClassNames } from './Hovercard.styles';
 import { HovercardHeaderProps } from './Hovercard.types';
 
-/**
- * Header of a `Hovercard` component. Used to maintain a consistent layout.
- */
 export class HovercardHeader extends React.Component<HovercardHeaderProps & CustomizableComponentProps> {
   public render() {
     const { className, children, theme = defaultTheme } = this.props;
@@ -23,5 +20,8 @@ export class HovercardHeader extends React.Component<HovercardHeaderProps & Cust
   }
 }
 
+/**
+ * Header of a `Hovercard` component. Used to maintain a consistent layout.
+ */
 @customizable('HovercardHeader', ['theme'])
 export default class CustomizableHovercardHeader extends HovercardHeader {}

src/components/Hovercard/HovercardHeader.tsx

@@ -8,10 +8,6 @@ import { FixedGridRow, FixedGridColumn, GutterSize } from '../FixedGrid';
 import { getClassNames } from './MessageBar.styles';
 import { MessageBarType, MessageBarProps } from './MessageBar.types';
 
-/**
- * A `MessageBar` displays relevant status information. You can use a `MessageBar` to tell the user
- * about a situation, and optionally provide actions for them to take.
- */
 export class MessageBar extends React.Component<MessageBarProps & CustomizableComponentProps> {
   public render() {
     const { actions, children, className, type = MessageBarType.INFO, theme = defaultTheme } = this.props;
@@ -32,5 +28,9 @@ export class MessageBar extends React.Component<MessageBarProps & CustomizableCo
   }
 }
 
+/**
+ * A `MessageBar` displays relevant status information. You can use a `MessageBar` to tell the user
+ * about a situation, and optionally provide actions for them to take.
+ */
 @customizable('MessageBar', ['theme'])
 export default class CustomizableMessageBar extends MessageBar {}

src/components/MessageBar/MessageBar.tsx

@@ -13,10 +13,6 @@ import { join } from '../../util/classNames';
 import { getClassNames } from './ModalDialog.styles';
 import { ModalDialogProps } from './ModalDialog.types';
 
-/**
- * A `ModalDialog` is a temporary, modal UI overlay that generally provides contextual app
- * information or requires user confirmation/input.
- */
 export class ModalDialog extends React.Component<ModalDialogProps & CustomizableComponentProps> {
   public render() {
     const { children, className, isOpen, onDismiss, size, theme = defaultTheme } = this.props;
@@ -69,5 +65,9 @@ export class ModalDialog extends React.Component<ModalDialogProps & Customizable
   };
 }
 
+/**
+ * A `ModalDialog` is a temporary, modal UI overlay that generally provides contextual app
+ * information or requires user confirmation/input.
+ */
 @customizable('ModalDialog', ['theme'])
 export default class CustomizableModalDialog extends ModalDialog {}

src/components/ModalDialog/ModalDialog.tsx

@@ -6,9 +6,6 @@ import { join } from '../../util/classNames';
 import { getClassNames } from './NavigationLink.styles';
 import { NavigationLinkProps } from './NavigationLink.types';
 
-/**
- * A `NavigationLink` renders an `a` tag for navigation between web pages.
- */
 export class NavigationLink extends React.Component<NavigationLinkProps & CustomizableComponentProps> {
   public render() {
     const {
@@ -41,5 +38,8 @@ export class NavigationLink extends React.Component<NavigationLinkProps & Custom
   }
 }
 
+/**
+ * A `NavigationLink` renders an `a` tag for navigation between web pages.
+ */
 @customizable('NavigationLink', ['theme'])
 export default class CustomizableNavigationLink extends NavigationLink {}

src/components/NavigationLink/NavigationLink.tsx

@@ -14,9 +14,6 @@ import './Picker.css'; // Required for the Callout content as there aren't JS st
 
 class SuggestionListBasePicker extends BasePicker<SuggestionItem, IBasePickerProps<SuggestionItem>> {}
 
-/**
- * Pickers are used to pick one or more entities (e.g. people, groups, topics) from a list with typeahead capabilities.
- */
 export class Picker extends React.Component<PickerProps & CustomizableComponentProps> {
   public render() {
     const {
@@ -101,5 +98,9 @@ export class Picker extends React.Component<PickerProps & CustomizableComponentP
     );
   };
 }
+
+/**
+ * Pickers are used to pick one or more entities (e.g. people, groups, topics) from a list with typeahead capabilities.
+ */
 @customizable('Picker', ['theme'])
 export default class CustomizablePicker extends Picker {}

src/components/Picker/Picker.tsx

@@ -16,10 +16,6 @@ import Spinner, { SpinnerColor, SpinnerSize } from '../Spinner';
 import { getClassNames } from './PreviewCard.styles';
 import { PreviewCardProps, PreviewCardState } from './PreviewCard.types';
 
-/**
- * PreviewCard is a compact representation of an uploaded file or other attachment. It supports an
- * editable description, and a loading experience (Spinner or percentage ProgressIndicator).
- */
 export class PreviewCard extends React.Component<PreviewCardProps & CustomizableComponentProps, PreviewCardState> {
   constructor(props: PreviewCardProps) {
     super(props);
@@ -156,5 +152,9 @@ export class PreviewCard extends React.Component<PreviewCardProps & Customizable
   }
 }
 
+/**
+ * PreviewCard is a compact representation of an uploaded file or other attachment. It supports an
+ * editable description, and a loading experience (Spinner or percentage ProgressIndicator).
+ */
 @customizable('PreviewCard', ['theme'])
 export default class CustomizablePreviewCard extends PreviewCard {}

src/components/PreviewCard/PreviewCard.tsx

@@ -6,10 +6,6 @@ import { ProgressIndicator as OfficeFabricProgressIndicator } from 'office-ui-fa
 import { getProgressIndicatorStyles } from './ProgressIndicator.styles';
 import { ProgressIndicatorProps } from './ProgressIndicator.types';
 
-/**
- * A `ProgressIndicator` is used to show the progress of an ongoing operation
- * e.g. a file upload.
- */
 export class ProgressIndicator extends React.Component<ProgressIndicatorProps & CustomizableComponentProps> {
   public render() {
     const { ariaValueText, percentComplete, className, theme = defaultTheme } = this.props;
@@ -25,5 +21,9 @@ export class ProgressIndicator extends React.Component<ProgressIndicatorProps &
   }
 }
 
+/**
+ * A `ProgressIndicator` is used to show the progress of an ongoing operation
+ * e.g. a file upload.
+ */
 @customizable('ProgressIndicator', ['theme'])
 export default class CustomizableProgressIndicator extends ProgressIndicator {}

src/components/ProgressIndicator/ProgressIndicator.tsx

@@ -33,10 +33,6 @@ const fabricSpinnerSizes = {
   [SpinnerSize.XSMALL]: FabricSpinnerSize.xSmall,
 };
 
-/**
- * A `Spinner` is an outline of a circle which animates around itself indicating to the user that
- * things are processing. It is shown when we're unsure how long a task will take.
- */
 export class Spinner extends React.Component<SpinnerProps & CustomizableComponentProps> {
   public render() {
     const {
@@ -77,5 +73,9 @@ export class Spinner extends React.Component<SpinnerProps & CustomizableComponen
   }
 }
 
+/**
+ * A `Spinner` is an outline of a circle which animates around itself indicating to the user that
+ * things are processing. It is shown when we're unsure how long a task will take.
+ */
 @customizable('Spinner', ['theme'])
 export default class CustomizableSpinner extends Spinner {}