Fixed API documentation rendering

sozi-projects · Aug 17, 2020 · bb4a333 · bb4a333
1 parent 50dca06
commit bb4a333
Show file tree

Hide file tree

Showing 33 changed files with 189 additions and 886 deletions.
diff --git a/README.jsdoc.md b/README.jsdoc.md
@@ -1,4 +1,6 @@
 
+![Sozi logo](sozi-logo-bg.png)
+
 This is the JavaScript API documentation for Sozi.
 
 Additional information about the Sozi project can be found at:

diff --git a/js/Controller.js b/js/Controller.js
diff --git a/js/Storage.js b/js/Storage.js
@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 import {SVGDocumentWrapper} from "./svg/SVGDocumentWrapper";
 import {backendList} from "./backend/AbstractBackend";
 import {EventEmitter} from "events";
@@ -12,7 +14,6 @@ import path from "path";
 
 /** File read/write manager.
  *
- * @category editor
  * @extends EventEmitter
  * @todo Add documentation.
  */
@@ -327,7 +328,7 @@ export class Storage extends EventEmitter {
         const contents = paths.map(relPath => {
             const absPath = path.join(svgLoc, relPath);
             return this.backend.loadSync(absPath);
-        })
+        });
         return contents.join("\n");
     }
 }
diff --git a/js/backend/AbstractBackend.js b/js/backend/AbstractBackend.js
@@ -2,35 +2,32 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 import {EventEmitter} from "events";
 
 /** The list of backends supported by the current editor.
  *
- * @category backend
- *
- * @type {AbstractBackend[]}
+ * @type {module:backend/AbstractBackend.AbstractBackend[]}
  */
 export const backendList = [];
 
 /** Add a backend to {@link backendList|the list of supported backends}.
  *
- * @category backend
- *
- * @param {AbstractBackend} backend - The backend to add.
+ * @param {module:backend/AbstractBackend.AbstractBackend} backend - The backend to add.
  */
 export function addBackend(backend) {
     backendList.push(backend);
 }
 
 /** Abstraction for the execution platform.
  *
- * @category backend
  * @extends EventEmitter
  */
 export class AbstractBackend extends EventEmitter {
     /** Common constructor for backends.
      *
-     * @param {Controller} controller - A controller instance.
+     * @param {module:Controller.Controller} controller - A controller instance.
      * @param {HTMLElement} container - The element that will contain the menu for choosing a backend.
      * @param {string} buttonId - The ID of the button to generate in the menu.
      * @param {string} buttonLabel - The text of the button to generate in the menu (already translated).
@@ -39,7 +36,7 @@ export class AbstractBackend extends EventEmitter {
         super();
 
         /** The controller for this backend.
-         * @type {Controller} */
+         * @type {module:Controller.Controller} */
         this.controller = controller;
 
         /** A list of files to save automatically.
@@ -59,14 +56,14 @@ export class AbstractBackend extends EventEmitter {
         window.addEventListener("focus", () => {
             this.hasFocus = true;
             /** Signals that the current editor window has received the focus.
-             * @event AbstractBackend#focus */
+             * @event module:backend/AbstractBackend#focus */
             this.emit("focus");
         });
 
         window.addEventListener("blur", () => {
             this.hasFocus = false;
             /** Signals that the current editor window has lost the focus.
-             * @event AbstractBackend#blur */
+             * @event module:backend/AbstractBackend#blur */
             this.emit("blur");
         });
     }
@@ -125,13 +122,13 @@ export class AbstractBackend extends EventEmitter {
      *
      * @param fileDescriptor - A file to load (backend-dependent).
      *
-     * @fires AbstractBackend#load
-     * @fires AbstractBackend#change
+     * @fires module:backend/AbstractBackend#load
+     * @fires module:backend/AbstractBackend#change
      */
     load(fileDescriptor) {
         // Not implemented
         /** Signals that a file has been loaded.
-         * @event AbstractBackend#load */
+         * @event module:backend/AbstractBackend#load */
         this.emit("load", fileDescriptor, "", "Not implemented");
     }
 
@@ -140,7 +137,7 @@ export class AbstractBackend extends EventEmitter {
     }
 
     /** Signals that a file has changed.
-     * @event AbstractBackend#change
+     * @event module:backend/AbstractBackend#change
      */
 
     /** Create a new file.
@@ -163,14 +160,14 @@ export class AbstractBackend extends EventEmitter {
      * @param fileDescriptor - The file to save (backend-dependent).
      * @param {string} data - The new content of the file.
      *
-     * @fires AbstractBackend#save
+     * @fires module:backend/AbstractBackend#save
      *
      * @todo Use a callback instead of an event
      */
     save(fileDescriptor, data) {
         // Not implemented
         /** Signals that a file has been saved.
-         * @event AbstractBackend#save */
+         * @event module:backend/AbstractBackend#save */
         this.emit("save", fileDescriptor, "Not implemented");
     }
 

diff --git a/js/backend/Electron.js b/js/backend/Electron.js
@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 import {AbstractBackend, addBackend} from "./AbstractBackend";
 import fs from "fs";
 import path from "path";
@@ -21,8 +23,7 @@ console.log("Current working dir: " + cwd);
 
 /** Electron backend.
  *
- * @category backend
- * @extends AbstractBackend
+ * @extends module:backend/AbstractBackend.AbstractBackend
  * @todo Add documentation.
  */
 export class Electron extends AbstractBackend {

diff --git a/js/backend/FileReader.js b/js/backend/FileReader.js
@@ -2,12 +2,13 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 import {AbstractBackend, addBackend} from "./AbstractBackend";
 
 /** Browser FileReader backend.
  *
- * @category backend
- * @extends AbstractBackend
+ * @extends module:backend/AbstractBackend.AbstractBackend
  * @todo Add documentation.
  */
 export class FileReaderBackend extends AbstractBackend {

diff --git a/js/backend/GoogleDrive.js b/js/backend/GoogleDrive.js
@@ -2,12 +2,13 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 import {AbstractBackend, addBackend} from "./AbstractBackend";
 
 /** Google Drive backend.
  *
- * @category backend
- * @extends AbstractBackend
+ * @extends module:backend/AbstractBackend.AbstractBackend
  * @todo Add documentation.
  */
 export class GoogleDrive extends AbstractBackend {

diff --git a/js/i18n.js b/js/i18n.js
@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 import Jed from "jed";
 import locales from "./locales";
 

diff --git a/js/model/CameraState.js b/js/model/CameraState.js
@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 function copyIfSet(dest, src, prop) {
     if (src.hasOwnProperty(prop)) {
         dest[prop] = src[prop];
@@ -10,7 +12,6 @@ function copyIfSet(dest, src, prop) {
 
 /** Camera state.
  *
- * @category model
  * @todo Add documentation.
  */
 export class CameraState {

diff --git a/js/model/Preferences.js b/js/model/Preferences.js
@@ -3,9 +3,9 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 /** Sozi editor preferences.
- *
- * @category model
  *
  * @todo Add documentation.
  */

diff --git a/js/model/Presentation.js b/js/model/Presentation.js
@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 import {EventEmitter} from "events";
 import {CameraState} from "./CameraState";
 import {hasReliableBoundaries} from "../player/Camera";
@@ -14,7 +16,6 @@ function copyIfSet(dest, src, prop) {
 
 /** Layer properties for a frame in a Sozi presentation.
  *
- * @category model
  * @todo Add documentation.
  */
 export class LayerProperties {
@@ -139,7 +140,6 @@ export class LayerProperties {
 
 /** A frame in a Sozi presentation.
  *
- * @category model
  * @todo Add documentation.
  */
 export class Frame {
@@ -316,7 +316,6 @@ export class Frame {
 
 /** Layer in an SVG document.
  *
- * @category model
  * @todo Add documentation.
  */
 export class Layer {
@@ -356,7 +355,6 @@ const SVG_NS = "http://www.w3.org/2000/svg";
 
 /** Sozi presentation.
  *
- * @category model
  * @extends EventEmitter
  * @todo Add documentation.
  */

diff --git a/js/model/Selection.js b/js/model/Selection.js
@@ -2,30 +2,30 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/** @module */
+
 /** Selection in the timeline of the Sozi editor.
  *
  * A Selection instance holds the currently selected
  * frames and layers of the presentation.
- *
- * @category model
  */
 export class Selection {
 
     /** Create an empty selection for a given presentation.
      *
-     * @param {Presentation} presentation - A Sozi presentation object
+     * @param {module:model/Presentation.Presentation} presentation - A Sozi presentation object
      */
     constructor(presentation) {
         /** The presentation where selections happen.
-         * @type {Presentation} */
+         * @type {module:model/Presentation.Presentation} */
         this.presentation = presentation;
 
         /** The list of selected frames.
-         * @type {Frame[]} */
+         * @type {module:model/Presentation.Frame[]} */
         this.selectedFrames = [];
 
         /** The list of selected layers.
-         * @type {Layer[]} */
+         * @type {module:model/Presentation.Layer[]} */
         this.selectedLayers = [];
     }
 
@@ -68,7 +68,7 @@ export class Selection {
 
     /** The frame that was selected last, `null` if no frame is selected.
      *
-     * @type {Frame}
+     * @type {module:model/Presentation.Frame}
      */
     get currentFrame() {
         return this.selectedFrames.length ?
@@ -78,7 +78,7 @@ export class Selection {
 
     /** Check whether this selection contains the given frames.
      *
-     * @param {Frame[]} frames - The frames to check.
+     * @param {module:model/Presentation.Frame[]} frames - The frames to check.
      * @return `true` if all the given frames are selected.
      */
     hasFrames(frames) {
@@ -87,7 +87,7 @@ export class Selection {
 
     /** Add a frame to this selection.
      *
-     * @param {Frame} frame - The frame to add.
+     * @param {module:model/Presentation.Frame} frame - The frame to add.
      */
     addFrame(frame) {
         if (this.selectedFrames.indexOf(frame) < 0) {
@@ -97,7 +97,7 @@ export class Selection {
 
     /** Remove a frame from this selection.
      *
-     * @param {Frame} frame - The frame to remove.
+     * @param {module:model/Presentation.Frame} frame - The frame to remove.
      */
     removeFrame(frame) {
         const index = this.selectedFrames.indexOf(frame);
@@ -111,7 +111,7 @@ export class Selection {
      * If the frame is not selected, add it to the selection,
      * otherwise, remove it.
      *
-     * @param {Frame} frame - The frame to add or remove.
+     * @param {module:model/Presentation.Frame} frame - The frame to add or remove.
      */
     toggleFrameSelection(frame) {
         const index = this.selectedFrames.indexOf(frame);
@@ -125,7 +125,7 @@ export class Selection {
 
     /** Check whether this selection contains the given layers.
      *
-     * @param {Layer[]} layers - The layers to check.
+     * @param {module:model/Presentation.Layer[]} layers - The layers to check.
      * @return `true` if all the given layers are selected.
      */
     hasLayers(layers) {
@@ -134,7 +134,7 @@ export class Selection {
 
     /** Add a layer to this selection.
      *
-     * @param {Layer} layer - The layer to add.
+     * @param {module:model/Presentation.Layer} layer - The layer to add.
      */
     addLayer(layer) {
         if (this.selectedLayers.indexOf(layer) < 0) {
@@ -144,7 +144,7 @@ export class Selection {
 
     /** Remove a layer from this selection.
      *
-     * @param {Layer} layer - The layer to remove.
+     * @param {module:model/Presentation.Layer} layer - The layer to remove.
      */
     removeLayer(layer) {
         const index = this.selectedLayers.indexOf(layer);
@@ -158,7 +158,7 @@ export class Selection {
      * If the layer is not selected, add it to the selection,
      * otherwise, remove it.
      *
-     * @param {Layer} layer - The layer to add or remove.
+     * @param {module:model/Presentation.Layer} layer - The layer to add or remove.
      */
     toggleLayerSelection(layer) {
         const index = this.selectedLayers.indexOf(layer);