Documentation updates (#2257)

* Document Backend

* Document RequestBuilder

* Document some of AnkiConnect

3 files changed, 79 insertions, 0 deletions

diff --git a/ext/js/background/backend.js b/ext/js/background/backend.js
index 2154b32a..b156e16f 100644
--- a/ext/js/background/backend.js
+++ b/ext/js/background/backend.js
@@ -38,7 +38,14 @@
  * wanakana
  */
 
+/**
+ * This class controls the core logic of the extension, including API calls
+ * and various forms of communication between browser tabs and external applications.
+ */
 class Backend {
+    /**
+     * Creates a new instance.
+     */
     constructor() {
         this._japaneseUtil = new JapaneseUtil(wanakana);
         this._environment = new Environment();
@@ -145,6 +152,10 @@ class Backend {
         ]);
     }
 
+    /**
+     * Initializes the instance.
+     * @returns {Promise<void>} A promise which is resolved when initialization completes.
+     */
     prepare() {
         if (this._preparePromise === null) {
             const promise = this._prepareInternal();
diff --git a/ext/js/background/request-builder.js b/ext/js/background/request-builder.js
index 2cdd6f0e..c9efd1b6 100644
--- a/ext/js/background/request-builder.js
+++ b/ext/js/background/request-builder.js
@@ -15,13 +15,29 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+/**
+ * This class is used to generate `fetch()` requests on the background page
+ * with additional controls over anonymity and error handling.
+ */
 class RequestBuilder {
+    /**
+     * A progress callback for a fetch read.
+     * @callback ProgressCallback
+     * @param {boolean} complete Whether or not the data has been completely read.
+     */
+
+    /**
+     * Creates a new instance.
+     */
     constructor() {
         this._onBeforeSendHeadersExtraInfoSpec = ['blocking', 'requestHeaders', 'extraHeaders'];
         this._textEncoder = new TextEncoder();
         this._ruleIds = new Set();
     }
 
+    /**
+     * Initializes the instance.
+     */
     async prepare() {
         try {
             await this._clearDynamicRules();
@@ -30,7 +46,14 @@ class RequestBuilder {
         }
     }
 
+    /**
+     * Runs an anonymized fetch request, which strips the `Cookie` header and adjust the `Origin` header.
+     * @param {string} url The URL to fetch.
+     * @param {RequestInit} init The initialization parameters passed to the `fetch` function.
+     * @returns {Promise<Response>} The response of the `fetch` call.
+     */
     async fetchAnonymous(url, init) {
+        fetch(1, 2);
         if (isObject(chrome.declarativeNetRequest)) {
             return await this._fetchAnonymousDeclarative(url, init);
         }
@@ -42,6 +65,12 @@ class RequestBuilder {
         return await this._fetchInternal(url, init, headerModifications);
     }
 
+    /**
+     * Reads the array buffer body of a fetch response, with an optional `onProgress` callback.
+     * @param {Response} response The response of a `fetch` call.
+     * @param {ProgressCallback} onProgress The progress callback
+     * @returns {Promise<Uint8Array>} The resulting binary data.
+     */
     static async readFetchResponseArrayBuffer(response, onProgress) {
         let reader;
         try {
diff --git a/ext/js/comm/anki-connect.js b/ext/js/comm/anki-connect.js
index 9e3bd871..4228c12b 100644
--- a/ext/js/comm/anki-connect.js
+++ b/ext/js/comm/anki-connect.js
@@ -19,7 +19,13 @@
  * AnkiUtil
  */
 
+/**
+ * This class controls communication with Anki via the AnkiConnect plugin.
+ */
 class AnkiConnect {
+    /**
+     * Creates a new instance.
+     */
     constructor() {
         this._enabled = false;
         this._server = null;
@@ -29,30 +35,59 @@ class AnkiConnect {
         this._apiKey = null;
     }
 
+    /**
+     * Gets the URL of the AnkiConnect server.
+     * @type {string}
+     */
     get server() {
         return this._server;
     }
 
+    /**
+     * Assigns the URL of the AnkiConnect server.
+     * @param {string} value The new server URL to assign.
+     */
     set server(value) {
         this._server = value;
     }
 
+    /**
+     * Gets whether or not server communication is enabled.
+     * @type {boolean}
+     */
     get enabled() {
         return this._enabled;
     }
 
+    /**
+     * Sets whether or not server communication is enabled.
+     * @param {boolean} value The enabled state.
+     */
     set enabled(value) {
         this._enabled = value;
     }
 
+    /**
+     * Gets the API key used when connecting to AnkiConnect.
+     * The value will be `null` if no API key is used.
+     * @type {?string}
+     */
     get apiKey() {
         return this._apiKey;
     }
 
+    /**
+     * Sets the API key used when connecting to AnkiConnect.
+     * @param {?string} value The API key to use, or `null` if no API key should be used.
+     */
     set apiKey(value) {
         this._apiKey = value;
     }
 
+    /**
+     * Checks whether a connection to AnkiConnect can be established.
+     * @returns {Promise<boolean>} `true` if the connection was made, `false` otherwise.
+     */
     async isConnected() {
         try {
             await this._invoke('version');
@@ -62,6 +97,10 @@ class AnkiConnect {
         }
     }
 
+    /**
+     * Gets the AnkiConnect API version number.
+     * @returns {Promise<number>} The version number
+     */
     async getVersion() {
         if (!this._enabled) { return null; }
         await this._checkVersion();