From 2400b10749bea2fec71de8433ab0be30b6fac202 Mon Sep 17 00:00:00 2001 From: Olivier Tassinari Date: Fri, 14 Jul 2017 16:03:53 +0200 Subject: [PATCH] [docs] Improve coverage (#7432) --- .../BottomNavigation/BottomNavigation.md | 4 +-- .../pages/component-api/Checkbox/Checkbox.md | 2 +- .../component-api/Checkbox/LabelCheckbox.md | 16 --------- docs/src/pages/component-api/Chip/Chip.md | 2 +- docs/src/pages/component-api/Dialog/Dialog.md | 2 +- docs/src/pages/component-api/Drawer/Drawer.md | 2 +- .../component-api/Form/FormControlLabel.md | 2 +- docs/src/pages/component-api/Menu/Menu.md | 2 +- .../pages/component-api/Radio/LabelRadio.md | 16 --------- docs/src/pages/component-api/Radio/Radio.md | 2 +- .../pages/component-api/Radio/RadioGroup.md | 2 +- docs/src/pages/component-api/Ripple/Ripple.md | 33 ------------------- .../pages/component-api/Ripple/TouchRipple.md | 22 ------------- .../pages/component-api/Snackbar/Snackbar.md | 2 +- .../pages/component-api/Switch/LabelSwitch.md | 16 --------- docs/src/pages/component-api/Switch/Switch.md | 2 +- .../pages/component-api/Tabs/TabIndicator.md | 27 --------------- .../component-api/Tabs/TabScrollButton.md | 25 -------------- docs/src/pages/component-api/Tabs/Tabs.md | 2 +- package.json | 3 +- scripts/build-api-docs.js | 32 +++++++++--------- scripts/generate-docs-markdown.js | 20 ++++++----- src/BottomNavigation/BottomNavigation.js | 8 ++--- src/Checkbox/Checkbox.js | 2 +- src/Chip/Chip.js | 3 +- src/Dialog/Dialog.js | 4 ++- src/Drawer/Drawer.js | 4 ++- src/Form/FormControlLabel.js | 2 +- src/Hidden/HiddenJs.js | 3 +- src/Menu/Menu.js | 4 +-- src/Radio/Radio.js | 2 +- src/Radio/RadioGroup.js | 2 +- src/Snackbar/Snackbar.js | 2 +- src/Switch/Switch.js | 2 +- src/Tabs/Tabs.js | 5 ++- src/internal/Backdrop.js | 3 ++ src/internal/ClickAwayListener.js | 3 ++ src/internal/Modal.js | 7 +++- src/internal/Popover.js | 7 ++-- src/internal/Portal.js | 3 ++ src/internal/SwitchBase.js | 2 +- src/internal/Transition.js | 2 ++ src/utils/withWidth.js | 2 ++ 43 files changed, 93 insertions(+), 215 deletions(-) delete mode 100644 docs/src/pages/component-api/Checkbox/LabelCheckbox.md delete mode 100644 docs/src/pages/component-api/Radio/LabelRadio.md delete mode 100644 docs/src/pages/component-api/Ripple/Ripple.md delete mode 100644 docs/src/pages/component-api/Ripple/TouchRipple.md delete mode 100644 docs/src/pages/component-api/Switch/LabelSwitch.md delete mode 100644 docs/src/pages/component-api/Tabs/TabIndicator.md delete mode 100644 docs/src/pages/component-api/Tabs/TabScrollButton.md diff --git a/docs/src/pages/component-api/BottomNavigation/BottomNavigation.md b/docs/src/pages/component-api/BottomNavigation/BottomNavigation.md index 8f29adf3d27aa2..caf384e2c8bee1 100644 --- a/docs/src/pages/component-api/BottomNavigation/BottomNavigation.md +++ b/docs/src/pages/component-api/BottomNavigation/BottomNavigation.md @@ -9,9 +9,9 @@ |:-----|:-----|:--------|:------------| | children * | node | | The content of the component. | | classes | object | | Useful to extend the style applied to components. | -| onChange | function | | Function called when the value changes.

**Signature:**
`function(event: event, value: string) => void`
*event:* The event that triggered the change
*value:* We default to the index of the child | +| onChange | function | | Callback fired when the value changes.

**Signature:**
`function(event: object, value: any) => void`
*event:* The event source of the callback
*value:* We default to the index of the child | | showLabels | bool | false | If `true`, all `BottomNavigationButton`s will show their labels. By default only the selected `BottomNavigationButton` will show its label. | -| value | number | | The value of the currently selected `BottomNavigationButton`. | +| value | any | | The value of the currently selected `BottomNavigationButton`. | Any other properties supplied will be spread to the root element. diff --git a/docs/src/pages/component-api/Checkbox/Checkbox.md b/docs/src/pages/component-api/Checkbox/Checkbox.md index cb5e0717597785..0958d57cd62fb0 100644 --- a/docs/src/pages/component-api/Checkbox/Checkbox.md +++ b/docs/src/pages/component-api/Checkbox/Checkbox.md @@ -20,7 +20,7 @@ | inputProps | object | | Properties applied to the `input` element. | | inputRef | function | | Use that property to pass a ref callback to the native input component. | | name | string | | | -| onChange | function | | Callback fired when the state is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* `change` event
*checked:* The `checked` value of the switch | +| onChange | function | | Callback fired when the state is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* The event source of the callback
*checked:* The `checked` value of the switch | | value | string | | The value of the component. | Any other properties supplied will be spread to the root element. diff --git a/docs/src/pages/component-api/Checkbox/LabelCheckbox.md b/docs/src/pages/component-api/Checkbox/LabelCheckbox.md deleted file mode 100644 index ec6f7d67869cc1..00000000000000 --- a/docs/src/pages/component-api/Checkbox/LabelCheckbox.md +++ /dev/null @@ -1,16 +0,0 @@ - - -# LabelCheckbox - - - -## Props -| Name | Type | Default | Description | -|:-----|:-----|:--------|:------------| -| classes | object | | Useful to extend the style applied to components. | -| disabled | bool | | If `true`, the control will be disabled. | -| label | node | | The text to be used in an enclosing label element. | -| labelClassName | string | | The className to be used in an enclosing label element. | - -Any other properties supplied will be spread to the root element. - diff --git a/docs/src/pages/component-api/Chip/Chip.md b/docs/src/pages/component-api/Chip/Chip.md index 9c8f7fdca2a363..d78d22fd26abfc 100644 --- a/docs/src/pages/component-api/Chip/Chip.md +++ b/docs/src/pages/component-api/Chip/Chip.md @@ -10,7 +10,7 @@ Chips represent complex entities in small blocks, such as a contact. | avatar | node | | Avatar element. | | classes | object | | Useful to extend the style applied to components. | | label | node | | The content of the label. | -| onRequestDelete | function | | Callback function fired when the delete icon is clicked. If set, the delete icon will be shown.

**Signature:**
`function(event: object) => void`
*event:* `onClick` event targeting the delete icon element. | +| onRequestDelete | function | | Callback function fired when the delete icon is clicked. If set, the delete icon will be shown.

**Signature:**
`function(event: object) => void`
*event:* The event source of the callback | Any other properties supplied will be spread to the root element. diff --git a/docs/src/pages/component-api/Dialog/Dialog.md b/docs/src/pages/component-api/Dialog/Dialog.md index 8ab51cf55ef0b6..dace6fec56eb97 100644 --- a/docs/src/pages/component-api/Dialog/Dialog.md +++ b/docs/src/pages/component-api/Dialog/Dialog.md @@ -23,7 +23,7 @@ Dialogs are overlaid modal paper based components with a backdrop. | onExit | TransitionCallback | | Callback fired before the dialog exits. | | onExited | TransitionCallback | | Callback fired when the dialog has exited. | | onExiting | TransitionCallback | | Callback fired when the dialog is exiting. | -| onRequestClose | Function | | Callback fired when the dialog requests to be closed. | +| onRequestClose | Function | | Callback fired when the component requests to be closed.

**Signature:**
`function(event: object) => void`
*event:* The event source of the callback | | open | boolean | false | If `true`, the Dialog is open. | | transition | union: Function
 Element<*>
| Fade | Transition component. | diff --git a/docs/src/pages/component-api/Drawer/Drawer.md b/docs/src/pages/component-api/Drawer/Drawer.md index 61144034062cfc..d63dd97fc0b35d 100644 --- a/docs/src/pages/component-api/Drawer/Drawer.md +++ b/docs/src/pages/component-api/Drawer/Drawer.md @@ -15,7 +15,7 @@ | elevation | number | 16 | The elevation of the drawer. | | enterTransitionDuration | number | duration.enteringScreen | Customizes duration of enter animation (ms) | | leaveTransitionDuration | number | duration.leavingScreen | Customizes duration of leave animation (ms) | -| onRequestClose | Function | | Callback fired when the internal modal requests to be closed. | +| onRequestClose | Function | | Callback fired when the component requests to be closed.

**Signature:**
`function(event: object) => void`
*event:* The event source of the callback | | open | boolean | false | If `true`, the drawer is open. | Any other properties supplied will be spread to the root element. diff --git a/docs/src/pages/component-api/Form/FormControlLabel.md b/docs/src/pages/component-api/Form/FormControlLabel.md index 8c6d9f776ef262..23ffdbe6c2e367 100644 --- a/docs/src/pages/component-api/Form/FormControlLabel.md +++ b/docs/src/pages/component-api/Form/FormControlLabel.md @@ -14,7 +14,7 @@ | inputRef | function | | Use that property to pass a ref callback to the native input component. | | label * | node | | The text to be used in an enclosing label element. | | name | string | | | -| onChange | function | | Callback fired when the state is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* `change` event
*checked:* The `checked` value of the switch | +| onChange | function | | Callback fired when the state is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* The event source of the callback
*checked:* The `checked` value of the switch | | value | string | | The value of the component. | Any other properties supplied will be spread to the root element. diff --git a/docs/src/pages/component-api/Menu/Menu.md b/docs/src/pages/component-api/Menu/Menu.md index fa63d0e22372fe..dfe30b8f8d5dec 100644 --- a/docs/src/pages/component-api/Menu/Menu.md +++ b/docs/src/pages/component-api/Menu/Menu.md @@ -17,7 +17,7 @@ | onExit | TransitionCallback | | Callback fired before the Menu exits. | | onExited | TransitionCallback | | Callback fired when the Menu has exited. | | onExiting | TransitionCallback | | Callback fired when the Menu is exiting. | -| onRequestClose | Function | | Callback function fired when the menu is requested to be closed. | +| onRequestClose | Function | | Callback fired when the component requests to be closed.

**Signature:**
`function(event: object) => void`
*event:* The event source of the callback | | open | boolean | false | If `true`, the menu is visible. | | transitionDuration | union: number
 'auto'
| 'auto' | The length of the transition in `ms`, or 'auto' | diff --git a/docs/src/pages/component-api/Radio/LabelRadio.md b/docs/src/pages/component-api/Radio/LabelRadio.md deleted file mode 100644 index 98d3322529284e..00000000000000 --- a/docs/src/pages/component-api/Radio/LabelRadio.md +++ /dev/null @@ -1,16 +0,0 @@ - - -# LabelRadio - - - -## Props -| Name | Type | Default | Description | -|:-----|:-----|:--------|:------------| -| classes | object | | Useful to extend the style applied to components. | -| disabled | bool | | If `true`, the control will be disabled. | -| label | node | | The text to be used in an enclosing label element. | -| labelClassName | string | | The className to be used in an enclosing label element. | - -Any other properties supplied will be spread to the root element. - diff --git a/docs/src/pages/component-api/Radio/Radio.md b/docs/src/pages/component-api/Radio/Radio.md index 6769935d8f47f7..6d432af4f3114b 100644 --- a/docs/src/pages/component-api/Radio/Radio.md +++ b/docs/src/pages/component-api/Radio/Radio.md @@ -18,7 +18,7 @@ | inputProps | object | | Properties applied to the `input` element. | | inputRef | function | | Use that property to pass a ref callback to the native input component. | | name | string | | | -| onChange | function | | Callback fired when the state is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* `change` event
*checked:* The `checked` value of the switch | +| onChange | function | | Callback fired when the state is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* The event source of the callback
*checked:* The `checked` value of the switch | | value | string | | The value of the component. | Any other properties supplied will be spread to the root element. diff --git a/docs/src/pages/component-api/Radio/RadioGroup.md b/docs/src/pages/component-api/Radio/RadioGroup.md index d1485aa8c50bf2..e52c8453538b6b 100644 --- a/docs/src/pages/component-api/Radio/RadioGroup.md +++ b/docs/src/pages/component-api/Radio/RadioGroup.md @@ -10,7 +10,7 @@ | children | node | | The content of the component. | | classes | object | | Useful to extend the style applied to components. | | name | string | | The name used to reference the value of the control. | -| onChange | function | | Callback fired when a radio button is selected.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* `change` event
*checked:* The `checked` value of the switch | +| onChange | function | | Callback fired when a radio button is selected.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* The event source of the callback
*checked:* The `checked` value of the switch | | selectedValue | string | | Value of the selected radio button | Any other properties supplied will be spread to the root element. diff --git a/docs/src/pages/component-api/Ripple/Ripple.md b/docs/src/pages/component-api/Ripple/Ripple.md deleted file mode 100644 index 205061b89c2d36..00000000000000 --- a/docs/src/pages/component-api/Ripple/Ripple.md +++ /dev/null @@ -1,33 +0,0 @@ -# Ripple - - - -## Props -| Name | Type | Default | Description | -|:-----|:-----|:--------|:------------| -| pulsate | bool | false | If `true`, the ripple pulsates, typically indicating the keyboard focus state of an element. | -| rippleSize * | number | | Diameter of the ripple. | -| rippleX * | number | | Horizontal position of the ripple center. | -| rippleY * | number | | Vertical position of the ripple center. | - -Any other properties supplied will be spread to the root element. -## Classes - -You can overrides all the class names injected by Material-UI thanks to the `classes` property. -This property accepts the following keys: -- `ripple` -- `rippleVisible` -- `rippleFast` -- `container` -- `containerLeaving` -- `containerPulsating` -- `@keyframes mui-ripple-enter` -- `@keyframes mui-ripple-exit` -- `@keyframes mui-ripple-pulsate` - -Have a look at [overriding with class names](/customization/overrides#overriding-with-class-names) -section for more detail. - -If using the `overrides` key of the theme as documented -[here](/customization/themes#customizing-all-instances-of-a-component-type), -you need to use the following style sheet name: `MuiRipple`. diff --git a/docs/src/pages/component-api/Ripple/TouchRipple.md b/docs/src/pages/component-api/Ripple/TouchRipple.md deleted file mode 100644 index d910e7134cf5f2..00000000000000 --- a/docs/src/pages/component-api/Ripple/TouchRipple.md +++ /dev/null @@ -1,22 +0,0 @@ -# TouchRipple - - - -## Props -| Name | Type | Default | Description | -|:-----|:-----|:--------|:------------| -| center | bool | false | If `true`, the ripple starts at the center of the component rather than at the point of interaction. | - -Any other properties supplied will be spread to the root element. -## Classes - -You can overrides all the class names injected by Material-UI thanks to the `classes` property. -This property accepts the following keys: -- `root` - -Have a look at [overriding with class names](/customization/overrides#overriding-with-class-names) -section for more detail. - -If using the `overrides` key of the theme as documented -[here](/customization/themes#customizing-all-instances-of-a-component-type), -you need to use the following style sheet name: `MuiTouchRipple`. diff --git a/docs/src/pages/component-api/Snackbar/Snackbar.md b/docs/src/pages/component-api/Snackbar/Snackbar.md index 125e7051fb2105..2c4fe48ea6d0c2 100644 --- a/docs/src/pages/component-api/Snackbar/Snackbar.md +++ b/docs/src/pages/component-api/Snackbar/Snackbar.md @@ -23,7 +23,7 @@ | onExit | TransitionCallback | | Callback fired before the transition is exiting. | | onExited | TransitionCallback | | Callback fired when the transition has exited. | | onExiting | TransitionCallback | | Callback fired when the transition is exiting. | -| onRequestClose | signature | | Callback fired when the component requests to be closed.
Typically `onRequestClose` is used to set state in the parent component, which is used to control the `Snackbar` `open` prop.
The `reason` parameter can optionally be used to control the response to `onRequestClose`, for example ignoring `clickaway`. | +| onRequestClose | signature | | Callback fired when the component requests to be closed.
Typically `onRequestClose` is used to set state in the parent component, which is used to control the `Snackbar` `open` prop.
The `reason` parameter can optionally be used to control the response to `onRequestClose`, for example ignoring `clickaway`.

**Signature:**
`function(event: object, reason: string) => void`
*event:* The event source of the callback
*reason:* Can be:`"timeout"` (`autoHideDuration` expired) or: `"clickaway"` | | open * | boolean | | If true, `Snackbar` is open. | | transition | union: Function
 Element<*>
| | Object with Transition component, props & create Fn. | diff --git a/docs/src/pages/component-api/Switch/LabelSwitch.md b/docs/src/pages/component-api/Switch/LabelSwitch.md deleted file mode 100644 index ffca8a8f59c206..00000000000000 --- a/docs/src/pages/component-api/Switch/LabelSwitch.md +++ /dev/null @@ -1,16 +0,0 @@ - - -# LabelSwitch - - - -## Props -| Name | Type | Default | Description | -|:-----|:-----|:--------|:------------| -| classes | object | | Useful to extend the style applied to components. | -| disabled | bool | | If `true`, the control will be disabled. | -| label | node | | The text to be used in an enclosing label element. | -| labelClassName | string | | The className to be used in an enclosing label element. | - -Any other properties supplied will be spread to the root element. - diff --git a/docs/src/pages/component-api/Switch/Switch.md b/docs/src/pages/component-api/Switch/Switch.md index f1f25bfa32c56b..46bdee0629a71f 100644 --- a/docs/src/pages/component-api/Switch/Switch.md +++ b/docs/src/pages/component-api/Switch/Switch.md @@ -17,7 +17,7 @@ | icon | node | | The icon to display when the component is unchecked. If a string is provided, it will be used as a font ligature. | | inputProps | object | | Properties applied to the `input` element. | | name | string | | | -| onChange | function | | Callback fired when the is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* `change` event
*checked:* The `checked` value of the switch | +| onChange | function | | Callback fired when the is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* The event source of the callback
*checked:* The `checked` value of the switch | | value | string | | The value of the component. | Any other properties supplied will be spread to the root element. diff --git a/docs/src/pages/component-api/Tabs/TabIndicator.md b/docs/src/pages/component-api/Tabs/TabIndicator.md deleted file mode 100644 index 275d8260673cca..00000000000000 --- a/docs/src/pages/component-api/Tabs/TabIndicator.md +++ /dev/null @@ -1,27 +0,0 @@ - - -# TabIndicator - -@ignore - internal component. - -## Props -| Name | Type | Default | Description | -|:-----|:-----|:--------|:------------| -| classes | object | | Useful to extend the style applied to components. | - -Any other properties supplied will be spread to the root element. - -## CSS API - -You can overrides all the class names injected by Material-UI thanks to the `classes` property. -This property accepts the following keys: -- `root` -- `colorAccent` -- `colorPrimary` - -Have a look at [overriding with class names](/customization/overrides#overriding-with-class-names) -section for more detail. - -If using the `overrides` key of the theme as documented -[here](/customization/themes#customizing-all-instances-of-a-component-type), -you need to use the following style sheet name: `MuiTabIndicator`. diff --git a/docs/src/pages/component-api/Tabs/TabScrollButton.md b/docs/src/pages/component-api/Tabs/TabScrollButton.md deleted file mode 100644 index 1c3faf55884c66..00000000000000 --- a/docs/src/pages/component-api/Tabs/TabScrollButton.md +++ /dev/null @@ -1,25 +0,0 @@ - - -# TabScrollButton - -@ignore - internal component. - -## Props -| Name | Type | Default | Description | -|:-----|:-----|:--------|:------------| -| classes | object | | Useful to extend the style applied to components. | - -Any other properties supplied will be spread to the root element. - -## CSS API - -You can overrides all the class names injected by Material-UI thanks to the `classes` property. -This property accepts the following keys: -- `root` - -Have a look at [overriding with class names](/customization/overrides#overriding-with-class-names) -section for more detail. - -If using the `overrides` key of the theme as documented -[here](/customization/themes#customizing-all-instances-of-a-component-type), -you need to use the following style sheet name: `MuiTabScrollButton`. diff --git a/docs/src/pages/component-api/Tabs/Tabs.md b/docs/src/pages/component-api/Tabs/Tabs.md index f8697bba61faa0..0a5dc561f75062 100644 --- a/docs/src/pages/component-api/Tabs/Tabs.md +++ b/docs/src/pages/component-api/Tabs/Tabs.md @@ -15,7 +15,7 @@ Notice that this Component is incompatible with server side rendering. | index * | union: [object Object]
 number
| | The index of the currently selected `Tab`. If you don't want any selected `Tab`, you can set this property to `false`. | | indicatorClassName | string | | The CSS class name of the indicator element. | | indicatorColor | union: [object Object],[object Object]
 string
| 'accent' | Determines the color of the indicator. | -| onChange * | function | | Function called when the index change. | +| onChange * | function | | Callback fired when the index changes.

**Signature:**
`function(event: object, index: number) => void`
*event:* The event source of the callback
*index:* We default to the index of the child | | scrollButtons | enum: 'auto'
 'on'
 'off'
| 'auto' | Determine behavior of scroll buttons when tabs are set to scroll `auto` will only present them on medium and larger viewports `on` will always present them `off` will never present them | | scrollable | bool | false | True invokes scrolling properties and allow for horizontally scrolling (or swiping) the tab bar. | | textColor | union: [object Object],[object Object],[object Object]
 string
| 'inherit' | Determines the color of the `Tab`. | diff --git a/package.json b/package.json index 9c8ae9f05aee2f..6bace85ad1391d 100644 --- a/package.json +++ b/package.json @@ -28,9 +28,8 @@ "build:copy-files": "babel-node ./scripts/copy-files.js", "build:umd:dev": "webpack --config scripts/umd.webpack.config.js", "build:umd:prod": "cross-env NODE_ENV=production webpack --config scripts/umd.webpack.config.js", - "build:docs": "babel-node ./scripts/build-api-docs.js", + "build:docs": "rimraf docs/src/pages/component-api/* && babel-node ./scripts/build-api-docs.js", "prettier": "find . -name \"*.js\" | grep -v -f .eslintignore | xargs prettier --write --single-quote --trailing-comma all --print-width 100", - "clean:docs": "rimraf docs/api/*", "clean:build": "rimraf build", "lint": "eslint . --cache && echo \"eslint: no lint errors\"", "prebuild": "npm run clean:build", diff --git a/scripts/build-api-docs.js b/scripts/build-api-docs.js index 37e0db86b7e40c..48268b8f181cf3 100644 --- a/scripts/build-api-docs.js +++ b/scripts/build-api-docs.js @@ -1,20 +1,19 @@ /* eslint-disable flowtype/require-valid-file-annotation */ /* eslint-disable no-console */ -import fs from 'fs'; +import { mkdir, readFile, writeFile, readdir, stat } from 'fs'; import path from 'path'; import * as reactDocgen from 'react-docgen'; import generateMarkdown from './generate-docs-markdown'; import createMuiTheme from '../src/styles/theme'; const theme = createMuiTheme(); -const ignoredItems = ['internal', 'HiddenJs.js']; const componentRegex = /^([A-Z][a-z]+)+\.js/; const docsDir = path.resolve(__dirname, '../docs/src/pages/component-api'); const srcDir = path.resolve(__dirname, '../src'); function ensureExists(pat, mask, cb) { - fs.mkdir(pat, mask, err => { + mkdir(pat, mask, err => { if (err) { if (err.code === 'EEXIST') { cb(null); // ignore the error if the folder already exists @@ -30,7 +29,6 @@ function ensureExists(pat, mask, cb) { function buildDocs(componentPath) { // eslint-disable-next-line global-require, import/no-dynamic-require const component = require(componentPath); - const styles = { classes: [], name: null, @@ -42,7 +40,11 @@ function buildDocs(componentPath) { styles.name = component.styleSheet.name; } - fs.readFile(componentPath, 'utf8', (err, src) => { + readFile(componentPath, 'utf8', (err, src) => { + if (src.match(/@ignore - internal component./)) { + return; + } + const relativePath = path.parse(path.relative(srcDir, componentPath)); const outputDir = path.resolve(docsDir, relativePath.dir); @@ -68,9 +70,10 @@ function buildDocs(componentPath) { console.log('Error creating directory', outputDir); return; } - fs.writeFile(path.resolve(outputDir, `${relativePath.name}.md`), markdown, err3 => { + writeFile(path.resolve(outputDir, `${relativePath.name}.md`), markdown, err3 => { if (err3) { console.log('Error writing markdown file', path.format(relativePath)); + return; } console.log('Built markdown docs for', path.format(relativePath)); }); @@ -79,21 +82,20 @@ function buildDocs(componentPath) { } function findComponents(dir) { - fs.readdir(dir, (err, items) => { + readdir(dir, (err, items) => { items.forEach(item => { - if (ignoredItems.includes(item)) { - return; - } - const itemPath = path.resolve(dir, item); - fs.stat(itemPath, (err2, stats) => { + stat(itemPath, (err2, stats) => { if (stats.isDirectory()) { - return findComponents(itemPath); + findComponents(itemPath); + return; } + if (!componentRegex.test(item)) { - return false; + return; } - return buildDocs(itemPath); + + buildDocs(itemPath); }); }); }); diff --git a/scripts/generate-docs-markdown.js b/scripts/generate-docs-markdown.js index d21135955940fb..572d6f0c197a5f 100644 --- a/scripts/generate-docs-markdown.js +++ b/scripts/generate-docs-markdown.js @@ -26,7 +26,7 @@ function getDeprecatedInfo(type) { return false; } -function generatePropDescription(required, description, type) { +function generatePropDescription(description, type) { let deprecated = ''; if (type.name === 'custom') { @@ -46,10 +46,18 @@ function generatePropDescription(required, description, type) { .replace(/\n/g, ' ') .replace(/\r/g, ''); - if (parsed.tags.some(tag => tag.title === 'ignore')) return null; + if (parsed.tags.some(tag => tag.title === 'ignore')) { + return null; + } + let signature = ''; - if (type.name === 'func' && parsed.tags.length > 0) { + if ( + (type.name === 'func' || + type.name === 'Function' || + (type.name === 'signature' && type.type === 'function')) && + parsed.tags.length > 0 + ) { // Remove new lines from tag descriptions to avoid markdown errors. parsed.tags.forEach(tag => { if (tag.description) { @@ -146,11 +154,7 @@ function generateProps(props) { text = Object.keys(props).sort().reduce((textProps, propRaw) => { const prop = getProp(props, propRaw); - const description = generatePropDescription( - prop.required, - prop.description, - prop.flowType || prop.type, - ); + const description = generatePropDescription(prop.description, prop.flowType || prop.type); if (description === null) { return textProps; diff --git a/src/BottomNavigation/BottomNavigation.js b/src/BottomNavigation/BottomNavigation.js index df73d195ca4c39..7417acdf033196 100644 --- a/src/BottomNavigation/BottomNavigation.js +++ b/src/BottomNavigation/BottomNavigation.js @@ -58,10 +58,10 @@ BottomNavigation.propTypes = { */ className: PropTypes.string, /** - * Function called when the value changes. + * Callback fired when the value changes. * - * @param {event} event The event that triggered the change - * @param {string} value We default to the index of the child + * @param {object} event The event source of the callback + * @param {any} value We default to the index of the child */ onChange: PropTypes.func, /** @@ -72,7 +72,7 @@ BottomNavigation.propTypes = { /** * The value of the currently selected `BottomNavigationButton`. */ - value: PropTypes.number, + value: PropTypes.any, }; BottomNavigation.defaultProps = { diff --git a/src/Checkbox/Checkbox.js b/src/Checkbox/Checkbox.js index befa26fd7cff75..a5a3646e14c8d6 100644 --- a/src/Checkbox/Checkbox.js +++ b/src/Checkbox/Checkbox.js @@ -99,7 +99,7 @@ Checkbox.propTypes = { /** * Callback fired when the state is changed. * - * @param {object} event `change` event + * @param {object} event The event source of the callback * @param {boolean} checked The `checked` value of the switch */ onChange: PropTypes.func, diff --git a/src/Chip/Chip.js b/src/Chip/Chip.js index 19893f2e1f1755..5a202f6296d14d 100644 --- a/src/Chip/Chip.js +++ b/src/Chip/Chip.js @@ -202,7 +202,8 @@ Chip.propTypes = { /** * Callback function fired when the delete icon is clicked. * If set, the delete icon will be shown. - * @param {object} event `onClick` event targeting the delete icon element. + * + * @param {object} event The event source of the callback */ onRequestDelete: PropTypes.func, /** diff --git a/src/Dialog/Dialog.js b/src/Dialog/Dialog.js index f9570824afb93b..ea30705ed29400 100644 --- a/src/Dialog/Dialog.js +++ b/src/Dialog/Dialog.js @@ -118,7 +118,9 @@ type Props = { */ onExited?: TransitionCallback, // eslint-disable-line react/sort-prop-types /** - * Callback fired when the dialog requests to be closed. + * Callback fired when the component requests to be closed. + * + * @param {object} event The event source of the callback */ onRequestClose?: Function, /** diff --git a/src/Drawer/Drawer.js b/src/Drawer/Drawer.js index 2bd70464cb6c8a..002d44ae5d043d 100644 --- a/src/Drawer/Drawer.js +++ b/src/Drawer/Drawer.js @@ -118,7 +118,9 @@ type Props = { */ leaveTransitionDuration?: number, /** - * Callback fired when the internal modal requests to be closed. + * Callback fired when the component requests to be closed. + * + * @param {object} event The event source of the callback */ onRequestClose?: Function, /** diff --git a/src/Form/FormControlLabel.js b/src/Form/FormControlLabel.js index b211aa7982ecfa..8a62e133f3c97e 100644 --- a/src/Form/FormControlLabel.js +++ b/src/Form/FormControlLabel.js @@ -105,7 +105,7 @@ FormControlLabel.propTypes = { /** * Callback fired when the state is changed. * - * @param {object} event `change` event + * @param {object} event The event source of the callback * @param {boolean} checked The `checked` value of the switch */ onChange: PropTypes.func, diff --git a/src/Hidden/HiddenJs.js b/src/Hidden/HiddenJs.js index 46691954b34069..1f5cfd118110d1 100644 --- a/src/Hidden/HiddenJs.js +++ b/src/Hidden/HiddenJs.js @@ -13,8 +13,7 @@ type Props = HiddenProps & { }; /** - * @ignore - * Responsively hides by omission. + * @ignore - internal component. */ function HiddenJs(props: Props) { const { diff --git a/src/Menu/Menu.js b/src/Menu/Menu.js index 96ed7383ce2d03..0e6492d1096595 100644 --- a/src/Menu/Menu.js +++ b/src/Menu/Menu.js @@ -62,9 +62,9 @@ type Props = DefaultProps & { */ onExited?: TransitionCallback, // eslint-disable-line react/sort-prop-types /** - * Callback function fired when the menu is requested to be closed. + * Callback fired when the component requests to be closed. * - * @param {event} event The event that triggered the close request + * @param {object} event The event source of the callback */ onRequestClose?: Function, /** diff --git a/src/Radio/Radio.js b/src/Radio/Radio.js index 73e4f7b8d32c61..d170ae93763bbf 100644 --- a/src/Radio/Radio.js +++ b/src/Radio/Radio.js @@ -90,7 +90,7 @@ RadioDocs.propTypes = { /** * Callback fired when the state is changed. * - * @param {object} event `change` event + * @param {object} event The event source of the callback * @param {boolean} checked The `checked` value of the switch */ onChange: PropTypes.func, diff --git a/src/Radio/RadioGroup.js b/src/Radio/RadioGroup.js index a90658296ee625..9743a339f188f0 100644 --- a/src/Radio/RadioGroup.js +++ b/src/Radio/RadioGroup.js @@ -107,7 +107,7 @@ RadioGroup.propTypes = { /** * Callback fired when a radio button is selected. * - * @param {object} event `change` event + * @param {object} event The event source of the callback * @param {boolean} checked The `checked` value of the switch */ onChange: PropTypes.func, diff --git a/src/Snackbar/Snackbar.js b/src/Snackbar/Snackbar.js index eb27ccab221e14..91374975d53d7d 100644 --- a/src/Snackbar/Snackbar.js +++ b/src/Snackbar/Snackbar.js @@ -167,7 +167,7 @@ type Props = DefaultProps & { * The `reason` parameter can optionally be used to control the response to `onRequestClose`, * for example ignoring `clickaway`. * - * @param {event} event The event that triggered the close request + * @param {object} event The event source of the callback * @param {string} reason Can be:`"timeout"` (`autoHideDuration` expired) or: `"clickaway"` */ onRequestClose?: (event: ?Event, reason: string) => void, diff --git a/src/Switch/Switch.js b/src/Switch/Switch.js index 18fd91668255c2..1371bb1d1d2051 100644 --- a/src/Switch/Switch.js +++ b/src/Switch/Switch.js @@ -129,7 +129,7 @@ Switch.propTypes = { /** * Callback fired when the is changed. * - * @param {object} event `change` event + * @param {object} event The event source of the callback * @param {boolean} checked The `checked` value of the switch */ onChange: PropTypes.func, diff --git a/src/Tabs/Tabs.js b/src/Tabs/Tabs.js index c4218e8f3c4c9f..3ae2aa98dc9b5a 100644 --- a/src/Tabs/Tabs.js +++ b/src/Tabs/Tabs.js @@ -332,7 +332,10 @@ Tabs.propTypes = { */ indicatorColor: PropTypes.oneOfType([PropTypes.oneOf(['accent', 'primary']), PropTypes.string]), /** - * Function called when the index change. + * Callback fired when the index changes. + * + * @param {object} event The event source of the callback + * @param {number} index We default to the index of the child */ onChange: PropTypes.func.isRequired, /** diff --git a/src/internal/Backdrop.js b/src/internal/Backdrop.js index 641d730d9b726f..a4faa19cde0132 100644 --- a/src/internal/Backdrop.js +++ b/src/internal/Backdrop.js @@ -43,6 +43,9 @@ type Props = { invisible?: boolean, }; +/** + * @ignore - internal component. + */ function Backdrop(props: Props) { const { children, classes, className, invisible, ...other } = props; diff --git a/src/internal/ClickAwayListener.js b/src/internal/ClickAwayListener.js index 1b70e5061fe91a..4d74732f6ae95d 100644 --- a/src/internal/ClickAwayListener.js +++ b/src/internal/ClickAwayListener.js @@ -12,6 +12,9 @@ const isDescendant = (el, target) => { return false; }; +/** + * @ignore - internal component. + */ class ClickAwayListener extends Component { static propTypes = { children: PropTypes.element.isRequired, diff --git a/src/internal/Modal.js b/src/internal/Modal.js index 5d11affdecaf80..581db225a4913e 100644 --- a/src/internal/Modal.js +++ b/src/internal/Modal.js @@ -136,7 +136,9 @@ type Props = DefaultProps & { */ onExited?: TransitionCallback, // eslint-disable-line react/sort-prop-types /** - * Callback fired when the modal requests to be closed. + * Callback fired when the component requests to be closed. + * + * @param {object} event The event source of the callback */ onRequestClose?: Function, /** @@ -149,6 +151,9 @@ type State = { exited: boolean, }; +/** + * @ignore - internal component. + */ class Modal extends Component { props: Props; diff --git a/src/internal/Popover.js b/src/internal/Popover.js index f97a2413f387aa..6e170fe1f76af2 100644 --- a/src/internal/Popover.js +++ b/src/internal/Popover.js @@ -162,9 +162,9 @@ type Props = DefaultProps & { */ onExited?: TransitionCallback, // eslint-disable-line react/sort-prop-types /** - * Callback function fired when the popover is requested to be closed. + * Callback fired when the component requests to be closed. * - * @param {event} event The event that triggered the close request + * @param {object} event The event source of the callback */ onRequestClose?: Function, /** @@ -187,6 +187,9 @@ type Props = DefaultProps & { transitionDuration: number | 'auto', }; +/** + * @ignore - internal component. + */ class Popover extends Component { props: Props; static defaultProps: DefaultProps = { diff --git a/src/internal/Portal.js b/src/internal/Portal.js index bfc25a444ee0b4..581540829b16b2 100644 --- a/src/internal/Portal.js +++ b/src/internal/Portal.js @@ -4,6 +4,9 @@ import { Component, Children } from 'react'; import PropTypes from 'prop-types'; import ReactDOM from 'react-dom'; +/** + * @ignore - internal component. + */ class Portal extends Component { static defaultProps = { open: false, diff --git a/src/internal/SwitchBase.js b/src/internal/SwitchBase.js index 514640ab3e9030..0f725cc6ada7e9 100644 --- a/src/internal/SwitchBase.js +++ b/src/internal/SwitchBase.js @@ -217,7 +217,7 @@ export default function createSwitch( /** * Callback fired when the is changed. * - * @param {object} event `change` event + * @param {object} event The event source of the callback * @param {boolean} checked The `checked` value of the switch */ onChange: PropTypes.func, diff --git a/src/internal/Transition.js b/src/internal/Transition.js index e40171e0d463d8..ec477d31f95a26 100644 --- a/src/internal/Transition.js +++ b/src/internal/Transition.js @@ -127,6 +127,8 @@ type Props = DefaultProps & { }; /** + * @ignore - internal component. + * * Drawn from https://raw.githubusercontent.com/react-bootstrap/react-overlays/master/src/Transition.js * * The Transition component lets you define and run CSS transitions with a simple declarative api. diff --git a/src/utils/withWidth.js b/src/utils/withWidth.js index f32754c46856de..201798c104911d 100644 --- a/src/utils/withWidth.js +++ b/src/utils/withWidth.js @@ -11,6 +11,7 @@ import { keys } from '../styles/breakpoints'; /** * By default, returns true if screen width is the same or greater than the given breakpoint. + * * @param screenWidth * @param breakpoint * @param inclusive - defaults to true @@ -24,6 +25,7 @@ export const isWidthUp = (breakpoint, screenWidth, inclusive = true) => { /** * By default, returns true if screen width is the same or less than the given breakpoint. + * * @param screenWidth * @param breakpoint * @param inclusive - defaults to true