Merge pull request #4616 from yurydelendik/jsdoc

Creates make.js code to build jsdoc.

docs/contents/api/index.md

@@ -5,4 +5,4 @@ template: layout.jade
 
 # API
 
-We're currently working on better API docs, but the API is well documented in [api.js](https://github.com/mozilla/pdf.js/blob/master/src/display/api.js).
+We're currently working on <a href="draft/index.html">better API docs</a>, but the API is well documented in [api.js](https://github.com/mozilla/pdf.js/blob/master/src/display/api.js).

make.js

@@ -42,6 +42,7 @@ var ROOT_DIR = __dirname + '/', // absolute path to project's root
     FIREFOX_BUILD_DIR = BUILD_DIR + '/firefox/',
     CHROME_BUILD_DIR = BUILD_DIR + '/chromium/',
     B2G_BUILD_DIR = BUILD_DIR + '/b2g/',
+    JSDOC_DIR = BUILD_DIR + 'jsdoc',
     EXTENSION_SRC_DIR = 'extensions/',
     LOCALE_SRC_DIR = 'l10n/',
     GH_PAGES_DIR = BUILD_DIR + 'gh-pages/',
@@ -135,6 +136,28 @@ target.generic = function() {
   cleanupJSSource(GENERIC_DIR + '/web/viewer.js');
 };
 
+target.jsdoc = function() {
+  echo();
+  echo('### Generating jsdoc');
+
+  var JSDOC_FILES = [
+    'src/doc_helper.js',
+    'src/display/api.js',
+    'src/shared/util.js'
+  ];
+
+  if (test('-d', JSDOC_DIR)) {
+    rm('-rf', JSDOC_DIR);
+  }
+
+  mkdir('-p',JSDOC_DIR);
+
+  exec('"node_modules/.bin/jsdoc" -d "' + JSDOC_DIR + '" ' +
+       JSDOC_FILES.join(' '));
+
+  echo();
+};
+
 //
 // make web
 // Generates the website for the project, by checking out the gh-pages branch
@@ -145,6 +168,7 @@ target.web = function() {
   target.generic();
   target.extension();
   target.b2g();
+  target.jsdoc();
 
   echo();
   echo('### Creating web site');
@@ -159,6 +183,7 @@ target.web = function() {
   mkdir('-p', GH_PAGES_DIR + EXTENSION_SRC_DIR + '/firefox');
   mkdir('-p', GH_PAGES_DIR + EXTENSION_SRC_DIR + '/chromium');
   mkdir('-p', GH_PAGES_DIR + EXTENSION_SRC_DIR + '/b2g');
+  mkdir('-p', GH_PAGES_DIR + '/api/draft/');
 
   cp('-R', GENERIC_DIR + '/*', GH_PAGES_DIR);
   cp(FIREFOX_BUILD_DIR + '/*.xpi', FIREFOX_BUILD_DIR + '/*.rdf',
@@ -167,6 +192,7 @@ target.web = function() {
      GH_PAGES_DIR + EXTENSION_SRC_DIR + 'chromium/');
   cp('-R', 'test/features', GH_PAGES_DIR);
   cp('-R', B2G_BUILD_DIR, GH_PAGES_DIR + EXTENSION_SRC_DIR + 'b2g/');
+  cp('-R', JSDOC_DIR + '/*', GH_PAGES_DIR + '/api/draft/');
 
   var wintersmith = require('wintersmith');
   var env = wintersmith('docs/config.json');

package.json

@@ -6,6 +6,7 @@
     "yargs": "~1.2.1"
   },
   "devDependencies": {
+    "jsdoc": "~3.3.0",
     "wintersmith": "2.0.x",
     "moment": "2.3.x",
     "underscore": "1.4.x",

src/doc_helper.js

@@ -0,0 +1,34 @@
+/* Copyright 2012 Mozilla Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ NOTE: This file is created as a helper to assist with JSDoc html files.
+       It is not for use in the executable code.
+*/
+
+/**
+ * PDFJS scope object that contains all functions, objects and variables related
+ * to the PDF.js.
+ * @constructor
+ */
+function PDFJS() {
+  // Mock class constructor. See src/display/api.js.
+}
+
+/**
+ * Represents the eventual result of an asynchronous operation.
+ * @external Promise
+ * @see {@link http://promisesaplus.com/ Promise/A+}
+ */

src/shared/util.js

@@ -914,6 +914,7 @@ function isPDFFunction(v) {
 /**
  * Legacy support for PDFJS Promise implementation.
  * TODO remove eventually
+ * @ignore
  */
 var LegacyPromise = PDFJS.LegacyPromise = (function LegacyPromiseClosure() {
   return function LegacyPromise() {