React autodoc is the foundation for generating the documentation for your React Components. React provides a built-in mechanism for runtime property validation. If you opt-in to using these, you can use this tool to automate your documentation similar to what JSDoc provides for raw functions.
react-autodoc contains two pieces. The primary piece is the
The second piece is opt-in. It is a webpack
esprima-loader transformer that
will modify your source code to include the annotations that Autodoc requires.
// button.jsvar Button = React;// button.autodoc.jsvar React = ;var Autodoc = ;var Button = ;var AutodocButton = React;
This will produce a table that looks like a richer version of the following:
Autodoc for Button
|Property Key||Type||Required||Default Value|
Why the webpack loader?
Webpack is a module loader that understands your entire dependency graph. It also has great support for loaders and transformations for pretty much anything.
Using webpack provides the convenience of builds for different environments so you donâ€™t have to add the any overhead to your project in production, but can easily include in development or qa environments.
The inline version of the propType annotations looks something like this:
propTypes:state:var tmp = ReactPropTypestmpannotations = type: 'enum<active|disabled|focused>' tmpmodifier:var tmp = ReactPropTypesisRequiredtmpannotations = type: 'enum<primary|secondary>' isRequired: true tmpchildren:var tmp = ReactPropTypesanyisRequiredtmpannotations = type: 'any' isRequired: true tmp
Alternatives to inline annotations that can still be explored are:
- Output the annotated date to a dynamic file for
react-autodocwhich can resolve the annotations by looking up a given
- Monkey patching React.PropTypes with runtime hints to what properties are
available. Some immediate trade-offs is we canâ€™t provide rich views into
CallExpressionpropTypes such as
React Autodoc Expected Annotations
tests/annotationsFor.js file contains the expected annotations for
Autodoc. Implementing this interface will give you the freedom to build on top
of either side of the Autodoc. You are free to reimplement
<Autodoc /> or
add your own build-step transformations to handle the annotating.
Copyright 2015 Skookum Digital Works, Inc. All Right Reserved