Documentation

Documenting properties

Property Naming

Where a property has the same or similar function to another component, please use the same property name.

Property description

Component property documentation is created automatically from comments in the source code, and from the attributes such as React.PropTypes. Required properties will automatically be marked as such in the generated documentation.

Comments take this form, before the React.PropTypes declaration (note the double **):

/**
 * The css class name of the root element.
 */
className: React.PropTypes.string,

The text of the comment is treated as Markdown. References to a componentName or property should be wrapped in backticks, highlighting can be used if appropriate, and links to other parts of the documentation or external resources are possible.

Description wording

There is some reasonably standard wording across the property docs. You don't have to stick to it religiously if there's a better way to express the purpose of a particular property (and we haven't been so good at enforcing it on new components and props, so you'll see some variation in places), but please use it where appropriate:

• arrayOf "An array of ..."
• bool "If true, ..."
• element "This is the ... to be displayed ..."
• function "Callback function fired when ..."
• object (style objects) "Override the inline-styles of ..."
• number Description varies - try and follow a relevant equivalent property from another component.
• string (className) "The css class name of ..."
• string (other) Description varies - try and follow a relevant equivalent property from another component.

Callback signature

The @param tag is used to document the parameters a function property passes to the callback.

/**
 * Callback function fired when the `Snackbar` is requested to be closed by a click outside the `Snackbar`, 
 * or after the `autoHideDuration` timer expires.
 *
 * The `reason` parameter can optionally be used to control the response to `onRequestClose`,
 * for example ignoring `clickaway`.
 *
 * @param {string} reason Can be:`"timeout"` (`autoHideDuration` expired) or: `"clickaway"`
 */
onRequestClose: React.PropTypes.func.isRequired,

If a callback receives multiple parameters, add one @param tag per parameter, in the order they are returned to the callback.

The @returns tag is used to describe the return value expected, if any.

Example for @returns with a description:

 /**
  * Callback function used to determine the filter of the auto complete.
  *
  * @param {string} searchText The text to search for within `dataSource`.
  * @param {string} key `dataSource` element, or `text` property on that element if it's not a string.
  * @returns {boolean} `true` indicates the auto complete list will include `key` when the input is `searchText`.
  */
 filter: React.PropTypes.func,

The description is optional:

 /**
  * Callback function used to determine the filter of the auto complete.
  *
  * @param {string} searchText The text to search for within `dataSource`.
  * @param {string} key `dataSource` element, or `text` property on that element if it's not a string.
  * @returns {boolean}
  */
 filter: React.PropTypes.func,

Internal properties

Certain components will have properties that are not intended for public use, for example properties that are controlled by a parent component. These can be hidden from the documentation by adding the @ignore tag.

/**
 * The material-ui theme applied to this component.
 * @ignore
 */
muiTheme: React.PropTypes.object.isRequired,

Deprecating properties

When a property is deprecated, it will be marked as such in the docs with a strikethrough on the property name, and "Deprecated:" before the deprecation description.

To deprecate a property, add:

import deprecated from '../utils/deprecatedPropType';

to the component source.

Wrap the the PropType with the deprecated function:

/**
 * The subheader string that will be displayed at the top of the list.
 */

 subheader: deprecated(React.PropTypes.node,
 'Instead, nest the `Subheader` component directly inside the `List`.'),

The description should describe the alternate implementation.

Remove the deprecated property from getDefaultProps() otherwise the warning will fire each time the component is mounted, as the default PropTypes are also checked.