From 2ca2c387fc6d3416310a4b20745ec5a10ef3fe1b Mon Sep 17 00:00:00 2001
From: Yury Delendik <ydelendik@mozilla.com>
Date: Sun, 13 Apr 2014 15:54:24 -0500
Subject: [PATCH] Creates make.js code to build jsdoc.

---
 docs/contents/api/index.md |  2 +-
 make.js                    | 26 ++++++++++++++++++++++++++
 package.json               |  1 +
 src/doc_helper.js          | 34 ++++++++++++++++++++++++++++++++++
 src/shared/util.js         |  1 +
 5 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 src/doc_helper.js

diff --git a/docs/contents/api/index.md b/docs/contents/api/index.md
index 435edeefd..cf9e66440 100644
--- a/docs/contents/api/index.md
+++ b/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).
\ No newline at end of file
+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).
diff --git a/make.js b/make.js
index bc2fad294..a93adc839 100644
--- a/make.js
+++ b/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');
diff --git a/package.json b/package.json
index b50285e13..bf27be0f9 100644
--- a/package.json
+++ b/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",
diff --git a/src/doc_helper.js b/src/doc_helper.js
new file mode 100644
index 000000000..00b770920
--- /dev/null
+++ b/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+}
+ */
diff --git a/src/shared/util.js b/src/shared/util.js
index 1aed2d57f..6dac6b406 100644
--- a/src/shared/util.js
+++ b/src/shared/util.js
@@ -922,6 +922,7 @@ function isPDFFunction(v) {
 /**
  * Legacy support for PDFJS Promise implementation.
  * TODO remove eventually
+ * @ignore
  */
 var LegacyPromise = PDFJS.LegacyPromise = (function LegacyPromiseClosure() {
   return function LegacyPromise() {