JSDoc Migration

Gruntfile.js

@@ -67,6 +67,10 @@ module.exports = function (grunt) {
             }
         },
         watch: {
+            jsdoc2md: {
+                files: ['<%= conf.src %>/**/*.js'],
+                tasks: ['jsdoc2md']
+            },
             scripts: {
                 files: ['<%= conf.src %>/**/*.js', '<%= conf.web %>/stock.js'],
                 tasks: ['docs']
@@ -179,25 +183,12 @@ module.exports = function (grunt) {
                 }
             }
         },
-        emu: {
-            api: {
-                src: '<%= conf.pkg.name %>.js',
-                dest: '<%= conf.web %>/docs/api-latest.md'
+        jsdoc2md: {
+            dist: {
+                src: 'dc.js',
+                dest: 'web/docs/api-latest.md'
             }
         },
-        toc: {
-            api: {
-                src: '<%= emu.api.dest %>',
-                dest: '<%= emu.api.dest %>'
-            }
-        },
-        markdown: {
-            html: {
-                src: '<%= emu.api.dest %>',
-                dest: '<%= conf.web %>/docs/index.html'
-            },
-            options: {markdownOptions: {highlight: 'manual'}}
-        },
         docco: {
             options: {
                 dst: '<%= conf.web %>/docs',
@@ -324,35 +315,10 @@ module.exports = function (grunt) {
         }
     });
 
-    // custom tasks
-    grunt.registerMultiTask('emu', 'Documentation extraction by emu.', function () {
-        var emu = require('emu'),
-            srcFile = this.files[0].src[0],
-            destFile = this.files[0].dest,
-            source = grunt.file.read(srcFile);
-        grunt.file.write(destFile, emu.getComments(source));
-        grunt.log.writeln('File \'' + destFile + '\' created.');
-    });
     grunt.registerTask('merge', 'Merge a github pull request.', function (pr) {
         grunt.log.writeln('Merge Github Pull Request #' + pr);
         grunt.task.run(['shell:merge:' + pr, 'test' , 'shell:amend']);
     });
-    grunt.registerMultiTask('toc', 'Generate a markdown table of contents.', function () {
-        var marked = require('marked'),
-            slugify = function (s) { return s.trim().replace(/[-_\s]+/g, '-').toLowerCase(); },
-            srcFile = this.files[0].src[0],
-            destFile = this.files[0].dest,
-            source = grunt.file.read(srcFile),
-            tokens = marked.lexer(source),
-            toc = tokens.filter(function (item) {
-                return item.type === 'heading' && item.depth === 2;
-            }).reduce(function (toc, item) {
-                return toc + '  * [' + item.text + '](#' + slugify(item.text) + ')\n';
-            }, '');
-
-        grunt.file.write(destFile, '# DC API\n' + toc + '\n' + source);
-        grunt.log.writeln('Added TOC to \'' + destFile + '\'.');
-    });
     grunt.registerTask('test-stock-example', 'Test a new rendering of the stock example web page against a ' +
         'baseline rendering', function (option) {
             require('./regression/stock-regression-test.js').testStockExample(this.async(), option === 'diff');
@@ -373,7 +339,7 @@ module.exports = function (grunt) {
 
     // task aliases
     grunt.registerTask('build', ['concat', 'uglify']);
-    grunt.registerTask('docs', ['build', 'copy', 'emu', 'toc', 'markdown', 'docco', 'fileindex']);
+    grunt.registerTask('docs', ['build', 'copy', 'jsdoc2md', 'docco', 'fileindex']);
     grunt.registerTask('web', ['docs', 'gh-pages']);
     grunt.registerTask('server', ['docs', 'fileindex', 'jasmine:specs:build', 'connect:server', 'watch:jasmine-docs']);
     grunt.registerTask('test', ['build', 'jasmine:specs', 'shell:hooks']);
@@ -383,6 +349,7 @@ module.exports = function (grunt) {
     grunt.registerTask('ci-pull', ['test', 'jasmine:specs:build', 'connect:server']);
     grunt.registerTask('lint', ['changed:jshint', 'changed:jscs']);
     grunt.registerTask('default', ['build']);
+    grunt.registerTask('jsdoc', ['jsdoc2md', 'watch:jsdoc2md']);
 };
 
 module.exports.jsFiles = [

package.json

@@ -45,6 +45,7 @@
     "grunt-docco2": "~0.2.0",
     "grunt-fileindex": "^0.1.0",
     "grunt-gh-pages": "~0.9.1",
+    "grunt-jsdoc-to-markdown": "~1.1.1",
     "grunt-jscs": "~1.2.0",
     "grunt-lib-phantomjs": "~0.6.0",
     "grunt-markdown": "~0.7.0",

src/bar-chart.js

@@ -1,38 +1,27 @@
 /**
-## Bar Chart
-Includes: [Stack Mixin](#stack Mixin), [Coordinate Grid Mixin](#coordinate-grid-mixin)
-
-Concrete bar chart/histogram implementation.
-
-Examples:
-
-* [Nasdaq 100 Index](http://dc-js.github.com/dc.js/)
-* [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html)
-#### dc.barChart(parent[, chartGroup])
-Create a bar chart instance and attach it to the given parent element.
-
-Parameters:
-* parent : string | node | selection | compositeChart - any valid
- [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying
- a dom block element such as a div; or a dom element or d3 selection.
- If the bar chart is a sub-chart in a [Composite Chart](#composite-chart) then pass in the parent composite
- chart instance.
-* chartGroup : string (optional) - name of the chart group this chart instance should be placed in.
- Interaction with a chart will only trigger events and redraws within the chart's group.
-
-Returns:
-A newly created bar chart instance
-
-```js
-// create a bar chart under #chart-container1 element using the default global chart group
-var chart1 = dc.barChart('#chart-container1');
-// create a bar chart under #chart-container2 element using chart group A
-var chart2 = dc.barChart('#chart-container2', 'chartGroupA');
-// create a sub-chart under a composite parent chart
-var chart3 = dc.barChart(compositeChart);
-```
-
-**/
+ * Concrete bar chart/histogram implementation.
+ * Examples:
+ * - [Nasdaq 100 Index](http://dc-js.github.com/dc.js/)
+ * - [Canadian City Crime Stats](http://dc-js.github.com/dc.js/crime/index.html)
+ * @name barChart
+ * @memberOf dc
+ * @mixes dc.stackMixin
+ * @mixes dc.coordinateGridMixin
+ * @example
+ * // create a bar chart under #chart-container1 element using the default global chart group
+ * var chart1 = dc.barChart('#chart-container1');
+ * // create a bar chart under #chart-container2 element using chart group A
+ * var chart2 = dc.barChart('#chart-container2', 'chartGroupA');
+ * // create a sub-chart under a composite parent chart
+ * var chart3 = dc.barChart(compositeChart);
+ * @param {String|node|d3.selection|dc.compositeChart} parent - Any valid
+ * [d3 single selector](https://github.com/mbostock/d3/wiki/Selections#selecting-elements) specifying
+ * a dom block element such as a div; or a dom element or d3 selection.  If the bar chart is a sub-chart
+ * in a [Composite Chart](#composite-chart) then pass in the parent composite chart instance.
+ * @param {String} [chartGroup] - The name of the chart group this chart instance should be placed in.
+ * Interaction with a chart will only trigger events and redraws within the chart's group.
+ * @returns {BarChart}
+ */
 dc.barChart = function (parent, chartGroup) {
     var MIN_BAR_WIDTH = 1;
     var DEFAULT_GAP_BETWEEN_BARS = 2;
@@ -185,15 +174,18 @@ dc.barChart = function (parent, chartGroup) {
     };
 
     /**
-    #### .centerBar(boolean)
-    Whether the bar chart will render each bar centered around the data position on x axis. Default: false
-
-    **/
-    _chart.centerBar = function (_) {
+     * Whether the bar chart will render each bar centered around the data position on x axis
+     * @name centerBar
+     * @memberOf dc.barChart
+     * @instance
+     * @param {Boolean} [centerBar=false]
+     * @returns {Boolean}
+     */
+    _chart.centerBar = function (centerBar) {
         if (!arguments.length) {
             return _centerBar;
         }
-        _centerBar = _;
+        _centerBar = centerBar;
         return _chart;
     };
 
@@ -202,17 +194,21 @@ dc.barChart = function (parent, chartGroup) {
     });
 
     /**
-    #### .barPadding([padding])
-    Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1.
-    Setting this value will also remove any previously set `gap`. See the
-    [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands)
-    for a visual description of how the padding is applied.
-    **/
-    _chart.barPadding = function (_) {
+     * Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1.
+     * Setting this value will also remove any previously set `gap`. See the
+     * [d3 docs](https://github.com/mbostock/d3/wiki/Ordinal-Scales#wiki-ordinal_rangeBands)
+     * for a visual description of how the padding is applied.
+     * @name barPadding
+     * @memberOf dc.barChart
+     * @instance
+     * @param {Number} [barPadding]
+     * @returns {Number}
+     */
+    _chart.barPadding = function (barPadding) {
         if (!arguments.length) {
             return _chart._rangeBandPadding();
         }
-        _chart._rangeBandPadding(_);
+        _chart._rangeBandPadding(barPadding);
         _gap = undefined;
         return _chart;
     };
@@ -222,26 +218,31 @@ dc.barChart = function (parent, chartGroup) {
     };
 
     /**
-    #### .outerPadding([padding])
-    Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts.
-    Will pad the width by `padding * barWidth` on each side of the chart.
-
-    Default: 0.5
-    **/
+     * Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts.
+     * Will pad the width by `padding * barWidth` on each side of the chart.
+     * @name outerPadding
+     * @memberOf dc.barChart
+     * @instance
+     * @param {Number} [padding=0.5]
+     * @returns {Number}
+     */
     _chart.outerPadding = _chart._outerRangeBandPadding;
 
     /**
-     #### .gap(gapBetweenBars)
-     Manually set fixed gap (in px) between bars instead of relying on the default auto-generated
-     gap.  By default the bar chart implementation will calculate and set the gap automatically
-     based on the number of data points and the length of the x axis.
-
-    **/
-    _chart.gap = function (_) {
+     * Manually set fixed gap (in px) between bars instead of relying on the default auto-generated
+     * gap.  By default the bar chart implementation will calculate and set the gap automatically
+     * based on the number of data points and the length of the x axis.
+     * @name gap
+     * @memberOf dc.barChart
+     * @instance
+     * @param {Number} [gap=2]
+     * @returns {Number}
+     */
+    _chart.gap = function (gap) {
         if (!arguments.length) {
             return _gap;
         }
-        _gap = _;
+        _gap = gap;
         return _chart;
     };
 
@@ -259,23 +260,25 @@ dc.barChart = function (parent, chartGroup) {
     };
 
     /**
-    #### .alwaysUseRounding([boolean])
-    Set or get whether rounding is enabled when bars are centered.  Default: false.  If false, using
-    rounding with centered bars will result in a warning and rounding will be ignored.  This flag
-    has no effect if bars are not centered.
-
-    When using standard d3.js rounding methods, the brush often doesn't align correctly with
-    centered bars since the bars are offset.  The rounding function must add an offset to
-    compensate, such as in the following example.
-    ```js
-    chart.round(function(n) {return Math.floor(n)+0.5});
-    ```
-    **/
-    _chart.alwaysUseRounding = function (_) {
+     * Set or get whether rounding is enabled when bars are centered.  Default: false.  If false, using
+     * rounding with centered bars will result in a warning and rounding will be ignored.  This flag
+     * has no effect if bars are not centered.
+     * When using standard d3.js rounding methods, the brush often doesn't align correctly with
+     * centered bars since the bars are offset.  The rounding function must add an offset to
+     * compensate, such as in the following example.
+     * @name alwaysUseRounding
+     * @memberOf dc.barChart
+     * @instance
+     * @example
+     * chart.round(function(n) {return Math.floor(n)+0.5});
+     * @param {Boolean} [alwaysUseRounding=false]
+     * @returns {Boolean}
+     */
+    _chart.alwaysUseRounding = function (alwaysUseRounding) {
         if (!arguments.length) {
             return _alwaysUseRounding;
         }
-        _alwaysUseRounding = _;
+        _alwaysUseRounding = alwaysUseRounding;
         return _chart;
     };