add more docs

krissalvador27 · Nov 19, 2017 · a1dce26 · a1dce26
1 parent 4967cb1
commit a1dce26
Show file tree

Hide file tree

Showing 9 changed files with 843 additions and 80 deletions.
diff --git a/docs/src/ComponentDocs.js b/docs/src/ComponentDocs.js
@@ -1,6 +1,8 @@
 import React from 'react';
 import ReactDOM from 'react-dom';
 import _ from 'lodash';
+import remark from 'remark';
+import remarkReact from 'remark-react';
 
 export default class ComponentDocs extends React.Component {
   render() {
@@ -13,7 +15,9 @@ export default class ComponentDocs extends React.Component {
 
       {propDocs.description ?
         <div className="row">
-          <p className="component-description">{propDocs.description}</p>
+          <p className="component-description">
+            {renderMarkdown(propDocs.description)}
+          </p>
         </div>
         : null
       }
@@ -25,18 +29,28 @@ export default class ComponentDocs extends React.Component {
             <strong>{propKey}</strong>: {_.get(propInfo, 'type.name', 'unknown')}
             {propInfo.description ? <br/> : null}
             {propInfo.description ?
-              <span className="prop-description">{propInfo.description}</span>
+              <span className="prop-description">
+                {renderMarkdown(propInfo.description)}
+              </span>
               : null}
 
             {propInfo.defaultValue ?
-              <div className="prop-default">default value: <code>{propInfo.defaultValue.value}</code></div>
+              <div className="prop-default">
+                default value: <code>{propInfo.defaultValue.value}</code>
+              </div>
               : null}
           </div>
         })}
-
       </div>
 
       {children}
     </div>
   }
+}
+
+function renderMarkdown(markdownText = '') {
+  return remark()
+    .use(remarkReact)
+    .processSync(markdownText)
+    .contents;
 }
diff --git a/docs/src/docs/BarChart/propDocs.json b/docs/src/docs/BarChart/propDocs.json
@@ -37,14 +37,14 @@
         "raw": "CustomPropTypes.xyObjectOf(PropTypes.func.isRequired)"
       },
       "required": false,
-      "description": ""
+      "description": "D3 scales for the X and Y axes of the chart, in {x, y} object format."
     },
     "data": {
       "type": {
         "name": "array"
       },
       "required": false,
-      "description": "",
+      "description": "Array of data to be plotted. One bar will be rendered per datum in the array.",
       "defaultValue": {
         "value": "[]",
         "computed": false
@@ -71,7 +71,7 @@
         "name": "bool"
       },
       "required": false,
-      "description": "",
+      "description": "Boolean which determines whether the chart will use horizontal or vertical bars.\nWhen `true`, bars will be horizontal, ie. the X-axis will be treated as the dependent axis.",
       "defaultValue": {
         "value": "false",
         "computed": false
@@ -82,31 +82,31 @@
         "name": "number"
       },
       "required": false,
-      "description": "",
+      "description": "Thickness (in pixels) of each bar (ie. bar height if `horizontal` is `true`, otherwise bar width).",
       "defaultValue": {
         "value": "8",
         "computed": false
       }
     },
-    "barClassName": {
+    "barStyle": {
       "type": {
-        "name": "string"
+        "name": "object"
       },
       "required": false,
-      "description": "",
+      "description": "Inline style object to be applied to each bar.",
       "defaultValue": {
-        "value": "''",
+        "value": "{}",
         "computed": false
       }
     },
-    "barStyle": {
+    "barClassName": {
       "type": {
-        "name": "object"
+        "name": "string"
       },
       "required": false,
-      "description": "",
+      "description": "Class attribute to be applied to each bar.",
       "defaultValue": {
-        "value": "{}",
+        "value": "''",
         "computed": false
       }
     },
@@ -116,28 +116,28 @@
         "raw": "CustomPropTypes.getter"
       },
       "required": false,
-      "description": ""
+      "description": "Data getter for class attribute to be applied to each bar. Whereas `className` passes the same class to all\nbars, this is a function called once per bar, which gets the bar's datum as its first argument,\nso that each bar may determine its own className."
     },
-    "onMouseEnterBar": {
+    "onMouseMoveBar": {
       "type": {
         "name": "func"
       },
       "required": false,
-      "description": ""
+      "description": "`mousemove` event handler callback, called when user's mouse moves within a bar."
     },
-    "onMouseMoveBar": {
+    "onMouseEnterBar": {
       "type": {
         "name": "func"
       },
       "required": false,
-      "description": ""
+      "description": "`mouseenter` event handler callback, called when user's mouse enters a bar."
     },
     "onMouseLeaveBar": {
       "type": {
         "name": "func"
       },
       "required": false,
-      "description": ""
+      "description": "`mouseleave` event handler callback, called when user's mouse leaves a bar."
     }
   }
 }
diff --git a/docs/src/docs/RangeBarChart/propDocs.json b/docs/src/docs/RangeBarChart/propDocs.json
@@ -1,5 +1,5 @@
 {
-  "description": "",
+  "description": "`RangeBarChart` is a variation on the standard bar chart. Just like a normal bar chart, each bar represents a single\nvalue on the *independent* axis (X axis for vertical bars), and is centered on this value.\nHowever, on the *dependent* axis, each bar represents a *range* (min/max) of values,\nrather than always starting at zero.",
   "methods": [
     {
       "name": "getDomain",
@@ -37,14 +37,14 @@
         "raw": "CustomPropTypes.xyObjectOf(PropTypes.func.isRequired)"
       },
       "required": false,
-      "description": ""
+      "description": "D3 scales for the X and Y axes of the chart, in {x, y} object format."
     },
     "data": {
       "type": {
         "name": "array"
       },
       "required": false,
-      "description": "",
+      "description": "Array of data to be plotted. One bar will be rendered per datum in this array.",
       "defaultValue": {
         "value": "[]",
         "computed": false
@@ -55,7 +55,7 @@
         "name": "bool"
       },
       "required": false,
-      "description": "",
+      "description": "Boolean which determines whether the chart will use horizontal or vertical bars.\nWhen `true`, bars will be horizontal, ie. the X-axis will be treated as the dependent axis.",
       "defaultValue": {
         "value": "false",
         "computed": false
@@ -67,62 +67,62 @@
         "raw": "CustomPropTypes.getter"
       },
       "required": false,
-      "description": ""
+      "description": "Data getter for bar X-value, called once per bar (datum).\nIf `horizontal` is `false`, this gets the *independent* variable value on which the bar is centered.\nIf `horizontal` is `true`, this gets the start (minimum value) of the *dependent* variable range which is spanned by the bar's length."
     },
     "getXEnd": {
       "type": {
         "name": "custom",
         "raw": "CustomPropTypes.getter"
       },
       "required": false,
-      "description": ""
+      "description": "Data getter for the end (maximum X-value) of the *dependent* variable range which is spanned by the bar's length.\nShould only be passed when `horizontal` is `true` (ignored otherwise)."
     },
     "getY": {
       "type": {
         "name": "custom",
         "raw": "CustomPropTypes.getter"
       },
       "required": false,
-      "description": ""
+      "description": "Data getter for bar Y-value, called once per bar (datum).\nIf `horizontal` is `false`, this gets the start (minimum value) of the *dependent* variable range which is spanned by the bar's length.\nIf `horizontal` is `true`, this gets the *independent* variable value on which the bar is centered."
     },
     "getYEnd": {
       "type": {
         "name": "custom",
         "raw": "CustomPropTypes.getter"
       },
       "required": false,
-      "description": ""
+      "description": "Data getter for the end (maximum Y-value) of the *dependent* variable range which is spanned by the bar's length.\nShould only be passed when `horizontal` is `false` (ignored otherwise)."
     },
     "barThickness": {
       "type": {
         "name": "number"
       },
       "required": false,
-      "description": "",
+      "description": "Thickness (in pixels) of each bar (ie. bar height if `horizontal` is `true`, otherwise bar width).",
       "defaultValue": {
         "value": "8",
         "computed": false
       }
     },
-    "barClassName": {
+    "barStyle": {
       "type": {
-        "name": "string"
+        "name": "object"
       },
       "required": false,
-      "description": "",
+      "description": "Inline style object to be applied to each bar.",
       "defaultValue": {
-        "value": "''",
+        "value": "{}",
         "computed": false
       }
     },
-    "barStyle": {
+    "barClassName": {
       "type": {
-        "name": "object"
+        "name": "string"
       },
       "required": false,
-      "description": "",
+      "description": "Class attribute to be applied to each bar.",
       "defaultValue": {
-        "value": "{}",
+        "value": "''",
         "computed": false
       }
     },
@@ -132,28 +132,28 @@
         "raw": "CustomPropTypes.getter"
       },
       "required": false,
-      "description": ""
+      "description": "Data getter for class attribute to be applied to each bar. Whereas `className` passes the same class to all\nbars, this is a function called once per bar, which gets the bar's datum as its first argument,\nso that each bar may determine its own className."
     },
-    "onMouseEnterBar": {
+    "onMouseMoveBar": {
       "type": {
         "name": "func"
       },
       "required": false,
-      "description": ""
+      "description": "`mousemove` event handler callback, called when user's mouse moves within a bar."
     },
-    "onMouseMoveBar": {
+    "onMouseEnterBar": {
       "type": {
         "name": "func"
       },
       "required": false,
-      "description": ""
+      "description": "`mouseenter` event handler callback, called when user's mouse enters a bar."
     },
     "onMouseLeaveBar": {
       "type": {
         "name": "func"
       },
       "required": false,
-      "description": ""
+      "description": "`mouseleave` event handler callback, called when user's mouse leaves a bar."
     }
   }
 }
diff --git a/package.json b/package.json
@@ -65,6 +65,8 @@
     "react-pure-render-debug": "^1.1.1",
     "react-router": "^4.1.2",
     "react-router-dom": "^4.1.2",
+    "remark": "^8.0.0",
+    "remark-react": "^4.0.1",
     "shelljs": "^0.7.8",
     "sinon": "^4.1.2",
     "sinon-chai": "^2.14.0",

diff --git a/src/AreaBarChart.js b/src/AreaBarChart.js
@@ -8,23 +8,65 @@ import {makeAccessor, domainFromRangeData} from './utils/Data';
 import xyPropsEqual from './utils/xyPropsEqual';
 import RangeRect from './RangeRect';
 
+/**
+ * `AreaBarChart` is a variation on the standard bar chart. Just like a normal bar chart, each bar represents a single
+ * value on the *dependent* axis (Y axis for vertical bars), and the bar stretches from zero to this value.
+ * However, on the *independent* axis, each bar represents a *range* (min/max) of values,
+ * rather than being centered on a specific value.
+ * In other words, the bar *lengths* act the same way as standard bar chart bars,
+ * but their *thicknesses* are variable and meaningful.
+ * `AreaBarChart`s are the correct way to display histograms with variable bin sizes.
+ * They are so named because, in cases like these histograms, since both the bar thickness and length are meaningful,
+ * so too is the bar's total *area*, unlike in other bar charts.
+ */
+
 export default class AreaBarChart extends React.Component {
   static propTypes = {
+    /**
+     * D3 scales for the X and Y axes of the chart, in {x, y} object format.
+     */
     scale: CustomPropTypes.xyObjectOf(PropTypes.func.isRequired),
+    /**
+     * Array of data to be plotted. One bar will be rendered per datum in this array.
+     */
     data: PropTypes.array,
+    /**
+     * Boolean which determines whether the chart will use horizontal or vertical bars.
+     * When `true`, bars will be horizontal, ie. the X-axis will be treated as the dependent axis.
+     */
     horizontal: PropTypes.bool,
 
     getX: CustomPropTypes.getter,
     getXEnd: CustomPropTypes.getter,
     getY: CustomPropTypes.getter,
     getYEnd: CustomPropTypes.getter,
-    getClass: CustomPropTypes.getter,
 
+    /**
+     * Class attribute to be applied to each bar.
+     */
     barClassName: PropTypes.string,
+    /**
+     * Data getter for class attribute to be applied to each bar. Whereas `className` passes the same class to all
+     * bars, this is a function called once per bar, which gets the bar's datum as its first argument,
+     * so that each bar may determine its own className.
+     */
+    getClass: CustomPropTypes.getter,
+    /**
+     * Inline style object to be applied to each bar.
+     */
     barStyle: PropTypes.object,
 
-    onMouseEnterBar: PropTypes.func,
+    /**
+     * `mousemove` event handler callback, called when user's mouse moves within a bar.
+     */
     onMouseMoveBar: PropTypes.func,
+    /**
+     * `mouseenter` event handler callback, called when user's mouse enters a bar.
+     */
+    onMouseEnterBar: PropTypes.func,
+    /**
+     * `mouseleave` event handler callback, called when user's mouse leaves a bar.
+     */
     onMouseLeaveBar: PropTypes.func
   };
   static defaultProps = {