Merge pull request #15025 from gasolin/issue-956634

Bug 956634 - [jsdoc] Enable generate all apps/ jsdoc, r=yurenju

Gruntfile.js

@@ -1,47 +1,58 @@
+/* global module, require */
 module.exports = function(grunt) {
   'use strict';
 
+  var fs = require('fs'),
+      path = require('path');
+  var JSDOCJSON = 'jsdoc.json';
+
+  // Load the plugin that provides tasks.
+  require('load-grunt-tasks')(grunt);
+  grunt.loadTasks('tasks');
+
+  // merge source to destination dict
+  function extend(destination, source) {
+    for (var property in source) {
+      if (source.hasOwnProperty(property)) {
+        destination[property] = source[property];
+      }
+    }
+    return destination;
+  }
+
+  var jsdocConfig = {
+    // per app configurations are defined in each app's jsdoc.json file
+    options: {
+      configure: '.jsdocrc',
+      lenient: true //comment this out to debug jsdoc strictly
+    }
+  };
+
+  // processing jsdoc configurations
+  var files = fs.readdirSync('apps');
+  files.forEach(function(filePath, i) {
+    var appName = path.join('apps', filePath);
+    if (fs.statSync(appName).isDirectory()) {
+      // read jsdoc.json file in each app
+      var jsonFile = path.join('apps', filePath, JSDOCJSON);
+      if (fs.existsSync(jsonFile)) {
+        console.log('... ' + filePath + ' config file found');
+        var appcfg = JSON.parse(fs.readFileSync(jsonFile,
+          { encoding: 'utf8' }));
+        extend(jsdocConfig, appcfg);
+      }
+    }
+  });
+
   // Project configuration
   grunt.initConfig({
     pkg: grunt.file.readJSON('package.json'),
     clean: {
       docs: ['docs/']
     },
-    jsdoc: {
-      system: {
-        src: ['apps/system/js/**/*.js',
-              // XXX Remove the following exclusion after related javascript
-              // features are supported by JSDocs parser.
-              '!apps/system/js/airplane_mode.js',
-              '!apps/system/js/sound_manager.js',
-              '!apps/system/js/title.js',
-              '!apps/system/js/value_selector/date_picker.js',
-              '!apps/system/js/value_selector/spin_date_picker.js',
-              '!apps/system/js/lockscreen.js',
-              '!apps/system/js/edge_swipe_detector.js',
-              '!apps/system/js/stack_manager.js',],
-        options: {
-          destination: 'docs/system'
-        }
-      },
-      keyboard: {
-        src: ['apps/keyboard/js/**/*.js',
-              '!apps/keyboard/js/render.js'],
-        options: {
-          destination: 'docs/keyboard'
-        }
-      },
-      options: {
-        configure: '.jsdocrc',
-        lenient: true
-      }
-    }
+    jsdoc: jsdocConfig
   });
 
-  // Load the plugin that provides tasks
-  grunt.loadNpmTasks('grunt-contrib-clean');
-  grunt.loadNpmTasks('grunt-jsdoc');
-
   // Default task(s)
   grunt.registerTask('docs', ['clean', 'jsdoc']);
 };

README.md

@@ -212,7 +212,15 @@ See [how to run the Gaia endurance tests](https://developer.mozilla.org/en-US/do
 
 To generate API reference locally, you have to install grunt with following command:
 
-    $ npm -g grunt-cli
+```sh
+$ npm -g grunt-cli
+```
 
 then run `make docs` command to generate docs.
 The generated API docs will be located in `docs` folder.
+
+You could generate single app doc with this:
+
+```sh
+$ grunt jsdoc:system
+```

apps/bluetooth/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "bluetooth": {
+    "src": ["apps/bluetooth/js/**/*.js"],
+    "options": {
+      "destination": "docs/bluetooth"
+    }
+  }
+}

apps/bookmark/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "bookmark": {
+    "src": ["apps/bookmark/js/**/*.js"],
+    "options": {
+      "destination": "docs/bookmark"
+    }
+  }
+}

apps/browser/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "browser": {
+    "src": ["apps/browser/js/**/*.js"],
+    "options": {
+      "destination": "docs/browser"
+    }
+  }
+}

apps/calendar/jsdoc.json

@@ -0,0 +1,15 @@
+{
+  "calendar": {
+    "src": ["apps/calendar/js/**/*.js",
+            "!apps/calendar/js/controllers/time.js",
+            "!apps/calendar/js/models/account.js",
+            "!apps/calendar/js/models/calendar.js",
+            "!apps/calendar/js/models/event.js",
+            "!apps/calendar/js/views/month_child.js"
+            ],
+    "options": {
+      "destination": "docs/calendar"
+    }
+  }
+}
+

apps/callscreen/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "callscreen": {
+    "src": ["apps/callscreen/js/**/*.js"],
+    "options": {
+      "destination": "docs/callscreen"
+    }
+  }
+}

apps/camera/jsdoc.json

@@ -0,0 +1,9 @@
+{
+  "camera": {
+    "src": ["apps/camera/README.md",
+            "apps/camera/js/**/*.js"],
+    "options": {
+      "destination": "docs/camera"
+    }
+  }
+}

apps/communications/jsdoc.json

@@ -0,0 +1,20 @@
+{
+  "contacts": {
+    "src": ["apps/communications/contacts/js/**/*.js"],
+    "options": {
+      "destination": "docs/contacts"
+    }
+  },
+  "dialer": {
+    "src": ["apps/communications/dialer/js/**/*.js"],
+    "options": {
+      "destination": "docs/dialer"
+    }
+  },
+  "ftu": {
+    "src": ["apps/communications/ftu/js/**/*.js"],
+    "options": {
+      "destination": "docs/ftu"
+    }
+  }
+}

apps/costcontrol/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "costcontrol": {
+    "src": ["apps/costcontrol/js/**/*.js"],
+    "options": {
+      "destination": "docs/costcontrol"
+    }
+  }
+}

apps/email/jsdoc.json

@@ -0,0 +1,11 @@
+{
+  "email": {
+    "src": ["apps/email/js/**/*.js",
+            "!apps/email/js/ext/mailapi/activesync/configurator.js"
+    ],
+    "options": {
+      "destination": "docs/email"
+    }
+  }
+}
+

apps/emergency-call/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "emergencycall": {
+    "src": ["apps/emergency-call/js/**/*.js"],
+    "options": {
+      "destination": "docs/emergency-call"
+    }
+  }
+}

apps/findmydevice/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "findmydevice": {
+    "src": ["apps/findmydevice/js/**/*.js"],
+    "options": {
+      "destination": "docs/findmydevice"
+    }
+  }
+}

apps/fl/jsdoc.json

@@ -0,0 +1,9 @@
+{
+  "fl": {
+    "src": ["apps/fl/js/**/*.js",
+            "!apps/fl/js/utils.js"],
+    "options": {
+      "destination": "docs/forwardlock"
+    }
+  }
+}

apps/fm/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "fm": {
+    "src": ["apps/fm/js/**/*.js"],
+    "options": {
+      "destination": "docs/fm"
+    }
+  }
+}

apps/gallery/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "gallery": {
+    "src": ["apps/gallery/js/**/*.js"],
+    "options": {
+      "destination": "docs/gallery"
+    }
+  }
+}

apps/homescreen/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "homescreen": {
+    "src": ["apps/homescreen/js/**/*.js"],
+    "options": {
+      "destination": "docs/homescreen"
+    }
+  }
+}

apps/keyboard/jsdoc.json

@@ -0,0 +1,10 @@
+{
+  "keyboard": {
+    "src": ["apps/keyboard/js/**/*.js",
+            "!apps/keyboard/js/render.js"
+    ],
+    "options": {
+      "destination": "docs/keyboard"
+    }
+  }
+}

apps/music/jsdoc.json

@@ -0,0 +1,11 @@
+{
+  "music": {
+    "src": ["apps/music/js/**/*.js",
+            "!apps/music/js/Player.js",
+            "!apps/music/js/music.js"
+    ],
+    "options": {
+      "destination": "docs/music"
+    }
+  }
+}

apps/operatorvariant/jsdoc.json

@@ -0,0 +1,11 @@
+{
+  "operatorvariant": {
+    "src": ["apps/operatorvariant/js/**/*.js",
+            "!apps/operatorvariant/js/operator_variant.js"
+    ],
+    "options": {
+      "destination": "docs/operatorvariant"
+    }
+  }
+}
+

apps/ringtones/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "ringtones": {
+    "src": ["apps/ringtones/js/**/*.js"],
+    "options": {
+      "destination": "docs/ringtones"
+    }
+  }
+}

apps/search/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "search": {
+    "src": ["apps/search/js/**/*.js"],
+    "options": {
+      "destination": "docs/search"
+    }
+  }
+}

apps/setringtone/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "setringtone": {
+    "src": ["apps/setringtone/js/**/*.js"],
+    "options": {
+      "destination": "docs/setringtone"
+    }
+  }
+}

apps/settings/jsdoc.json

@@ -0,0 +1,16 @@
+{
+  "settings": {
+    "src": ["apps/settings/README.md",
+            "apps/settings/js/**/*.js",
+            "!apps/settings/js/carrier.js",
+            "!apps/settings/js/mvvm/views.js",
+            "!apps/settings/js/settings.js",
+            "!apps/settings/js/wifi.js",
+            "!apps/settings/js/modules/mvvm/list_view.js",
+            "!apps/settings/js/panels/send_feedback/send_feedback.js"
+    ],
+    "options": {
+      "destination": "docs/settings"
+    }
+  }
+}

apps/sms/jsdoc.json

@@ -0,0 +1,10 @@
+{
+  "sms": {
+    "src": ["apps/sms/js/**/*.js",
+            "!apps/sms/js/desktop-only/contacts.js"],
+    "options": {
+      "destination": "docs/sms"
+    }
+  }
+}
+

apps/system/jsdoc.json

@@ -0,0 +1,21 @@
+{
+  "system": {
+    "src": ["apps/system/js/**/*.js",
+            "!apps/system/js/airplane_mode.js",
+            "!apps/system/js/sound_manager.js",
+            "!apps/system/js/title.js",
+            "!apps/system/js/value_selector/date_picker.js",
+            "!apps/system/js/value_selector/spin_date_picker.js",
+            "!apps/system/js/lockscreen.js",
+            "!apps/system/js/edge_swipe_detector.js",
+            "!apps/system/js/stack_manager.js",
+            "!apps/system/js/lockscreen_window.js",
+            "!apps/system/js/lockscreen_window_manager.js",
+            "!apps/system/js/media_playback.js",
+            "!apps/system/js/radio.js"
+    ],
+    "options": {
+     "destination": "docs/system"
+    }
+  }
+}

apps/video/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "video": {
+    "src": ["apps/video/js/**/*.js"],
+    "options": {
+      "destination": "docs/video"
+    }
+  }
+}

apps/wallpaper/jsdoc.json

@@ -0,0 +1,8 @@
+{
+  "wallpaper": {
+    "src": ["apps/wallpaper/js/**/*.js"],
+    "options": {
+      "destination": "docs/wallpaper"
+    }
+  }
+}