Adds types definitions (jsdoc) for the PDFViewer code.

web/interfaces.js

@@ -0,0 +1,77 @@
+/* -*- Mode: Java; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* 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.
+ */
+
+'use strict';
+
+/**
+ * @interface
+ */
+function IPDFLinkService() {}
+IPDFLinkService.prototype = {
+  /**
+   * @returns {number}
+   */
+  get page() {},
+  /**
+   * @param {number} value
+   */
+  set page(value) {},
+  /**
+   * @param dest - The PDF destination object.
+   */
+  navigateTo: function (dest) {},
+  /**
+   * @param dest - The PDF destination object.
+   * @returns {string} The hyperlink to the PDF object.
+   */
+  getDestinationHash: function (dest) {},
+  /**
+   * @param hash - The PDF parameters/hash.
+   * @returns {string} The hyperlink to the PDF object.
+   */
+  getAnchorUrl: function (hash) {},
+};
+
+/**
+ * @interface
+ */
+function IRenderableView() {}
+IRenderableView.prototype = {
+  /**
+   * @returns {string} - Unique ID for rendering queue.
+   */
+  get renderingId() {},
+  /**
+   * @returns {RenderingStates}
+   */
+  get renderingState() {},
+  /**
+   * @param {function} callback - The draw completion callback.
+   */
+  draw: function (callback) {},
+  resume: function () {},
+};
+
+/**
+ * @interface
+ */
+function ILastScrollSource() {}
+ILastScrollSource.prototype = {
+  /**
+   * @returns {number}
+   */
+  get lastScroll() {},
+};

web/page_view.js

@@ -20,6 +20,20 @@
 
 'use strict';
 
+/**
+ * @constructor
+ * @param {HTMLDivElement} container - The viewer element.
+ * @param {number} id - The page unique ID (normally its number).
+ * @param {number} scale - The page scale display.
+ * @param {PageViewport} defaultViewport - The page viewport.
+ * @param {IPDFLinkService} linkService - The navigation/linking service.
+ * @param {PDFRenderingQueue} renderingQueue - The rendering queue object.
+ * @param {Cache} cache - The page cache.
+ * @param {PDFPageSource} pageSource
+ * @param {PDFViewer} viewer
+ *
+ * @implements {IRenderableView}
+ */
 var PageView = function pageView(container, id, scale, defaultViewport,
                                  linkService, renderingQueue, cache,
                                  pageSource, viewer) {

web/pdf_rendering_queue.js

@@ -26,7 +26,14 @@ var RenderingStates = {
   FINISHED: 3
 };
 
+/**
+ * Controls rendering of the views for pages and thumbnails.
+ * @class
+ */
 var PDFRenderingQueue = (function PDFRenderingQueueClosure() {
+  /**
+   * @constructs
+   */
   function PDFRenderingQueue() {
     this.pdfViewer = null;
     this.pdfThumbnailViewer = null;
@@ -38,16 +45,26 @@ var PDFRenderingQueue = (function PDFRenderingQueueClosure() {
     this.isThumbnailViewEnabled = false;
   }
 
-  PDFRenderingQueue.prototype = {
+  PDFRenderingQueue.prototype = /** @lends PDFRenderingQueue.prototype */ {
+    /**
+     * @param {PDFViewer} pdfViewer
+     */
     setViewer: function PDFRenderingQueue_setViewer(pdfViewer) {
       this.pdfViewer = pdfViewer;
     },
 
+    /**
+     * @param {PDFThumbnailViewer} pdfThumbnailViewer
+     */
     setThumbnailViewer:
         function PDFRenderingQueue_setThumbnailViewer(pdfThumbnailViewer) {
       this.pdfThumbnailViewer = pdfThumbnailViewer;
     },
 
+    /**
+     * @param {IRenderableView} view
+     * @returns {boolean}
+     */
     isHighestPriority: function PDFRenderingQueue_isHighestPriority(view) {
       return this.highestPriorityPage === view.renderingId;
     },
@@ -120,13 +137,20 @@ var PDFRenderingQueue = (function PDFRenderingQueueClosure() {
       return null;
     },
 
+    /**
+     * @param {IRenderableView} view
+     * @returns {boolean}
+     */
     isViewFinished: function PDFRenderingQueue_isViewFinished(view) {
       return view.renderingState === RenderingStates.FINISHED;
     },
 
-    // Render a page or thumbnail view. This calls the appropriate function
-    // based on the views state. If the view is already rendered it will return
-    // false.
+    /**
+     * Render a page or thumbnail view. This calls the appropriate function
+     * based on the views state. If the view is already rendered it will return
+     * false.
+     * @param {IRenderableView} view
+     */
     renderView: function PDFRenderingQueue_renderView(view) {
       var state = view.renderingState;
       switch (state) {

web/pdf_viewer.js

@@ -34,7 +34,26 @@ var IGNORE_CURRENT_POSITION_ON_ZOOM = false;
 //#include page_view.js
 //#include text_layer_builder.js
 
+/**
+ * @typedef {Object} PDFViewerOptions
+ * @property {HTMLDivElement} container - The container for the viewer element.
+ * @property {HTMLDivElement} viewer - (optional) The viewer element.
+ * @property {IPDFLinkService} linkService - The navigation/linking service.
+ * @property {PDFRenderingQueue} renderingQueue - (optional) The rendering
+ *   queue object.
+ */
+
+/**
+ * Simple viewer control to display PDF content/pages.
+ * @class
+ * @implements {ILastScrollSource}
+ * @implements {IRenderableView}
+ */
 var PDFViewer = (function pdfViewer() {
+  /**
+   * @constructs PDFViewer
+   * @param {PDFViewerOptions} options
+   */
   function PDFViewer(options) {
     this.container = options.container;
     this.viewer = options.viewer || options.container.firstElementChild;
@@ -56,7 +75,7 @@ var PDFViewer = (function pdfViewer() {
     this._resetView();
   }
 
-  PDFViewer.prototype = {
+  PDFViewer.prototype = /** @lends PDFViewer.prototype */{
     get pagesCount() {
       return this.pages.length;
     },
@@ -496,6 +515,12 @@ var PDFViewer = (function pdfViewer() {
       });
     },
 
+    /**
+     * @param textLayerDiv {HTMLDivElement}
+     * @param pageIndex {number}
+     * @param viewport {PageViewport}
+     * @returns {TextLayerBuilder}
+     */
     createTextLayerBuilder: function (textLayerDiv, pageIndex, viewport) {
       var isViewerInPresentationMode =
         this.presentationModeState === PresentationModeState.FULLSCREEN;
@@ -517,13 +542,26 @@ var PDFViewer = (function pdfViewer() {
   return PDFViewer;
 })();
 
+/**
+ * PDFPage object source.
+ * @class
+ */
 var PDFPageSource = (function PDFPageSourceClosure() {
+  /**
+   * @constructs
+   * @param {PDFDocument} pdfDocument
+   * @param {number} pageNumber
+   * @constructor
+   */
   function PDFPageSource(pdfDocument, pageNumber) {
     this.pdfDocument = pdfDocument;
     this.pageNumber = pageNumber;
   }
 
-  PDFPageSource.prototype = {
+  PDFPageSource.prototype = /** @lends PDFPageSource.prototype */ {
+    /**
+     * @returns {Promise<PDFPage>}
+     */
     getPage: function () {
       return this.pdfDocument.getPage(this.pageNumber);
     }

web/text_layer_builder.js

@@ -28,11 +28,23 @@ function isAllWhitespace(str) {
   return !NonWhitespaceRegexp.test(str);
 }
 
+/**
+ * @typedef {Object} TextLayerBuilderOptions
+ * @property {HTMLDivElement} textLayerDiv - The text layer container.
+ * @property {number} pageIndex - The page index.
+ * @property {PageViewport} viewport - The viewport of the text layer.
+ * @property {ILastScrollSource} lastScrollSource - The object that records when
+ *   last time scroll happened.
+ * @property {boolean} isViewerInPresentationMode
+ * @property {PDFFindController} findController
+ */
+
 /**
  * TextLayerBuilder provides text-selection functionality for the PDF.
  * It does this by creating overlay divs over the PDF text. These divs
  * contain text that matches the PDF text they are overlaying. This object
  * also provides a way to highlight text that is being searched for.
+ * @class
  */
 var TextLayerBuilder = (function TextLayerBuilderClosure() {
   function TextLayerBuilder(options) {

web/thumbnail_view.js

@@ -21,6 +21,17 @@
 
 var THUMBNAIL_SCROLL_MARGIN = -19;
 
+/**
+ * @constructor
+ * @param container
+ * @param id
+ * @param defaultViewport
+ * @param linkService
+ * @param renderingQueue
+ * @param pageSource
+ *
+ * @implements {IRenderableView}
+ */
 var ThumbnailView = function thumbnailView(container, id, defaultViewport,
                                            linkService, renderingQueue,
                                            pageSource) {
@@ -241,7 +252,22 @@ var ThumbnailView = function thumbnailView(container, id, defaultViewport,
 
 ThumbnailView.tempImageCache = null;
 
+/**
+ * @typedef {Object} PDFThumbnailViewerOptions
+ * @property {HTMLDivElement} container - The container for the thumbs elements.
+ * @property {IPDFLinkService} linkService - The navigation/linking service.
+ * @property {PDFRenderingQueue} renderingQueue - The rendering queue object.
+ */
+
+/**
+ * Simple viewer control to display thumbs for pages.
+ * @class
+ */
 var PDFThumbnailViewer = (function pdfThumbnailViewer() {
+  /**
+   * @constructs
+   * @param {PDFThumbnailViewerOptions} options
+   */
   function PDFThumbnailViewer(options) {
     this.container = options.container;
     this.renderingQueue = options.renderingQueue;

web/viewer.js

@@ -92,8 +92,11 @@ var PDFView = {
   pdfDocument: null,
   sidebarOpen: false,
   printing: false,
+  /** @type {PDFViewer} */
   pdfViewer: null,
+  /** @type {PDFThumbnailViewer} */
   pdfThumbnailViewer: null,
+  /** @type {PDFRenderingQueue} */
   pdfRenderingQueue: null,
   pageRotation: 0,
   updateScaleControls: true,