docs(callbacks): document remaining callbacks (#1445)

* fix(docs): fix page not found routes

* fix(factories): consistent @returns jsdoc tag

* docs(Table): document renderBodyRow signature

* docs(Search): document all function signatures

* docs(Dropdown): document all function signatures

* docs(ComponentProps): simplify deafult prop column

* docs(Accordion): doc remaining callback signatures

* refactor(docs): consistent doc block closings

* fix(Root): lint error

docs/app/Components/ComponentDoc/ComponentProps.js

@@ -9,6 +9,8 @@ const descriptionExtraStyle = {
   color: '#777',
 }
 
+const getTagType = tag => tag.type.type === 'AllLiteral' ? 'any' : tag.type.name
+
 /**
  * Displays a table of a Component's PropTypes.
  */
@@ -56,32 +58,36 @@ export default class ComponentProps extends Component {
     const defaultValue = _.get(item, 'defaultValue.value')
     if (_.isNil(defaultValue)) return null
 
-    const defaultIsString = defaultValue[0] === "'"
-
-    return <code>{defaultIsString ? `=${defaultValue}` : `={${defaultValue}}`}</code>
+    return <code>{defaultValue}</code>
   }
 
   renderFunctionSignature = (item) => {
-    if (item.type !== '{func}') return
-
     const params = _.filter(item.tags, { title: 'param' })
+    const returns = _.find(item.tags, { title: 'returns' })
+
+    // this doesn't look like a function propType doc block
+    // don't try to render a signature
+    if (_.isEmpty(params) && !returns) return
+
     const paramSignature = params
-      .map(param => `${param.name}: ${param.type.name}`)
+      .map(param => `${param.name}: ${getTagType(param)}`)
       .join(', ')
 
-    const paramDescriptions = params.map(param => (
-      <div style={{ color: '#888' }} key={param.name}>
-        <strong>{param.name}</strong> - {param.description}
+    const tagDescriptions = _.compact([...params, returns]).map(tag => (
+      <div style={{ color: '#888' }} key={tag.name}>
+        <strong>{tag.name || tag.title}</strong> - {tag.description}
       </div>
     ))
 
-    const signature = <pre><code>{item.name}({paramSignature})</code></pre>
+    const signature = (
+      <pre><code>{item.name}({paramSignature}){returns ? `: ${getTagType(returns)}` : ''}</code></pre>
+    )
 
     return (
       <div>
         <strong>Signature:</strong>
         {signature}
-        {paramDescriptions}
+        {tagDescriptions}
       </div>
     )
   }

docs/app/Components/Root.js

@@ -3,7 +3,6 @@ import _ from 'lodash/fp'
 import React, { Component, PropTypes } from 'react'
 
 import ComponentDoc from '../Components/ComponentDoc/ComponentDoc'
-import PageNotFound from '../Views/PageNotFound'
 import { META } from 'src/lib'
 import * as semanticUIReact from 'src'
 
@@ -22,7 +21,7 @@ export default class Root extends Component {
     const componentName = _.startCase(name).replace(/ /g, '')
     const component = semanticUIReact[componentName]
     if (!component || !component._meta || !META.isParent(component)) {
-      return <PageNotFound />
+      return null
     }
 
     return (

docs/app/routes.js

@@ -15,11 +15,11 @@ const RedirectToIntro = () => <Redirect to='introduction' />
 const Router = () => (
   <BrowserRouter>
     <Layout>
-      <Route path='/' render={RedirectToIntro} />
-      <Route path='/introduction' component={Introduction} />
-      <Route path='/usage' component={Usage} />
-      <Route path='/:type/:name' component={Root} />
-      <Route path='/*' component={PageNotFound} />
+      <Route exact path='/' render={RedirectToIntro} />
+      <Route exact path='/introduction' component={Introduction} />
+      <Route exact path='/usage' component={Usage} />
+      <Route exact path='/:type/:name' component={Root} />
+      <Route exact path='/*' component={PageNotFound} />
     </Layout>
   </BrowserRouter>
 )

src/collections/Table/Table.js

@@ -172,8 +172,11 @@ Table.propTypes = {
   ]),
 
   /**
-   * A function that takes (data, index) and returns shorthand for a TableRow
-   * to be placed within Table.Body.
+   * Mapped over `tableData` and should return shorthand for each Table.Row to be placed within Table.Body.
+   *
+   * @param {*} data - An element in the `tableData` array.
+   * @param {number} index - The index of the current element in `tableData`.
+   * @returns {*} Shorthand for a Table.Row.
    */
   renderBodyRow: customPropTypes.every([
     customPropTypes.disallow(['children']),

src/lib/factories.js

@@ -98,7 +98,7 @@ export function createShorthand(Component, mapValueToProps, val, defaultProps =
  * @param {function|string} Component A ReactClass or string
  * @param {function} mapValueToProps A function that maps a primitive value to the Component props
  * @param {boolean} [generateKey] Whether or not to generate a child key, useful for collections.
- * @return {function} A shorthand factory function waiting for `val` and `defaultProps`.
+ * @returns {function} A shorthand factory function waiting for `val` and `defaultProps`.
  */
 export function createShorthandFactory(Component, mapValueToProps, generateKey) {
   if (typeof Component !== 'function' && typeof Component !== 'string') {

src/modules/Accordion/Accordion.js

@@ -48,7 +48,12 @@ export default class Accordion extends Component {
     /** Format for dark backgrounds. */
     inverted: PropTypes.bool,
 
-    /** Called with (event, index) when a panel title is clicked. */
+    /**
+     * Called when a panel title is clicked.
+     *
+     * @param {SyntheticEvent} event - React's original SyntheticEvent.
+     * @param {index} - The index of the clicked panel.
+     */
     onTitleClick: PropTypes.func,
 
     /**

src/modules/Dropdown/Dropdown.js

@@ -250,7 +250,15 @@ export default class Dropdown extends Component {
       PropTypes.oneOf(['left', 'right', 'top', 'top left', 'top right', 'bottom', 'bottom left', 'bottom right']),
     ]),
 
-    /** A function that takes (data, index, defaultLabelProps) and returns shorthand for Label. */
+    /**
+     * Mapped over the active items and returns shorthand for the active item Labels.
+     * Only applies to `multiple` Dropdowns.
+     *
+     * @param {object} item - A currently active dropdown item.
+     * @param {number} index - The current index.
+     * @param {object} defaultLabelProps - The default props for an active item Label.
+     * @returns {*} Shorthand for a Label.
+     */
     renderLabel: PropTypes.func,
 
     /** A dropdown can have its menu scroll. */

src/modules/Search/Search.js

@@ -86,14 +86,18 @@ export default class Search extends Component {
     // ------------------------------------
 
     /**
-     * A function that returns the category contents.
-     * Receives all SearchCategory props.
+     * Renders the SearchCategory contents.
+     *
+     * @param {object} props - The SearchCategory props object.
+     * @returns {*} - Renderable SearchCategory contents.
      */
     categoryRenderer: PropTypes.func,
 
     /**
-     * A function that returns the result contents.
-     * Receives all SearchResult props.
+     * Renders the SearchResult contents.
+     *
+     * @param {object} props - The SearchResult props object.
+     * @returns {*} - Renderable SearchResult contents.
      */
     resultRenderer: PropTypes.func,
 
@@ -420,9 +424,9 @@ export default class Search extends Component {
     const { category, results } = this.props
 
     return !category ? results : _.reduce(results,
-      (memo, categoryData) => memo.concat(categoryData.results),
-      []
-    )
+        (memo, categoryData) => memo.concat(categoryData.results),
+        []
+      )
   }
 
   getSelectedResult = (index = this.state.selectedIndex) => {

src/modules/Search/SearchCategory.js

@@ -9,8 +9,6 @@ import {
   useKeyOnly,
 } from '../../lib'
 
-const defaultRenderer = ({ name }) => name
-
 function SearchCategory(props) {
   const { active, children, className, renderer } = props
   const classes = cx(
@@ -24,7 +22,7 @@ function SearchCategory(props) {
   return (
     <ElementType {...rest} className={classes}>
       <div className='name'>
-        {renderer ? renderer(props) : defaultRenderer(props)}
+        {renderer(props)}
       </div>
       {children}
     </ElementType>
@@ -37,6 +35,10 @@ SearchCategory._meta = {
   type: META.TYPES.MODULE,
 }
 
+SearchCategory.defaultProps = {
+  renderer: ({ name }) => name,
+}
+
 SearchCategory.propTypes = {
   /** An element type to render as (string or function). */
   as: customPropTypes.as,
@@ -54,8 +56,10 @@ SearchCategory.propTypes = {
   name: PropTypes.string,
 
   /**
-   * A function that returns the category contents.
-   * Receives all SearchCategory props.
+   * Renders the category contents.
+   *
+   * @param {object} props - The SearchCategory props object.
+   * @returns {*} - Renderable category contents.
    */
   renderer: PropTypes.func,
 

src/modules/Search/SearchResult.js

@@ -58,15 +58,21 @@ export default class SearchResult extends Component {
     price: PropTypes.string,
 
     /**
-     * A function that returns the result contents.
-     * Receives all SearchResult props.
+     * Renders the result contents.
+     *
+     * @param {object} props - The SearchResult props object.
+     * @returns {*} - Renderable result contents.
      */
     renderer: PropTypes.func,
 
     /** Display title. */
     title: PropTypes.string,
   }
 
+  static defaultProps = {
+    renderer: defaultRenderer,
+  }
+
   handleClick = (e) => {
     const { onClick } = this.props
 
@@ -100,7 +106,7 @@ export default class SearchResult extends Component {
     // the style in any way let's just do that.
     return (
       <ElementType {...rest} className={classes} onClick={this.handleClick}>
-        {renderer ? renderer(this.props) : defaultRenderer(this.props)}
+        {renderer(this.props)}
       </ElementType>
     )
   }

src/views/Comment/Comment.js

@@ -19,7 +19,7 @@ import CommentText from './CommentText'
 
 /**
  * A comment displays user feedback to site content.
- * */
+ */
 function Comment(props) {
   const { className, children, collapsed } = props