Docs: lots of comments styled using JSDoc syntax

Including some typification, useful for validators (since JavaScript is an untyped language).

Author: GwynethLlewelyn

gwynethllewelyn/postlocalstorage/composer.json

@@ -4,7 +4,7 @@
 	"description": "A very simple phpBB3 extension to locally store the content of a post being written, to avoid losing everything after a crash or session expiration.",
 	"homepage": "https://github.com/GwynethLlewelyn/post-local-storage",
 	"version": "1.1.0",
-	"time": "2024-04-15",
+	"time": "2024-04-17",
 	"license": "GPL-2.0-only",
 	"keywords": [
 		"phpbb",

gwynethllewelyn/postlocalstorage/styles/all/template/postlocalstorage_functions.js

@@ -1,37 +1,62 @@
-// Copyright (C) 2023,2024 Gwyneth Llewelyn
-//
-// This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2.
-//
-// This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+/**
+ * postlocalstorage_functions.js
+ * Handles the content storage of a post/reply/direct message inside localStorage.
+ *
+ * @author Gwyneth Llewelyn
+ * @copyright © 2023,2024 by Gwyneth Llewelyn. Some rights reserved.
+ * @license GPL-2.0-only
+ */
 
+/**
+ * @function anonymous
+ *
+ * @param {Object} message - This object (will be set to `this`).
+ * @param {Document} doc - This object's DOM (will be set to `this.document`).
+ */
 (function(message, doc) {
-	var nIntervId; //
+	/**
+	 * Handler for the SetInterval event, so we can remove it on submit.
+	 * @type {number}
+	 * @since 1.1.0
+	 */
+	var nIntervId;
 
-	// One year = 31536000000 milliseconds.
+	/**
+	 * Freshness interval in milliseconds.
+	 * One year = 31536000000 milliseconds.
+	 * @const {number}
+	 */
 	const FRESHNESS_INTERVAL = 365 * 24 * 60 * 60 * 1000;
 
 	// If there is no localStorage support, give up
 	if (!message.localStorage) {
 		console.debug("no local storage support");
 		return;
 	}
-	// phpBB3 uses a textarea with name 'message', both for Quick Replies _and_ normal replies
+	/**
+	 * phpBB3 uses a textarea with name 'message', both for Quick Replies _and_ normal replies
+	 * @type {Element?}
+	 */
 	var textarea = doc.querySelector('textarea[name="message"]');
 	// no point in being around if this is nil; also: avoids crashing below (gwyneth 20220303)
 	if (!textarea) {
 		console.warn("no phpBB3 content body textarea found");
 		return;
 	}
-	// phpBB3 usually gives the subject/topic the name 'subject' — same for QR and normal replies.
+	/**
+	 * phpBB3 usually gives the subject/topic the name 'subject' — same for QR and normal replies.
+	 * @type {Element?}
+	 */
 	var subject = doc.querySelector('input[name="subject"]');
 	if (!subject) {
 		console.debug("no phpBB3 subject line found");
 		// I have not decided what to do in this case! Possibly just:
 		// subject = "(no subject)";
 	}
-	// The key for the key/value pair in localStorage is the current URL.
+	/**
+	 * The key for the key/value pair in localStorage is the current URL.
+	 * @type {string}
+	 */
 	var key = message.location.href;
 	// Firefox seems to have an odd bug which affects clicking backspace in quick succession.
 	// Kudos to @gvp9000 and for the fix below. (gwyneth 20240414)
@@ -40,16 +65,38 @@
 	for (let i = 0; i < count_hash_num - 1; i++) {
 		key = key.substring(0, key.lastIndexOf('#'));
 	}
-	// JSON object to be saved with the textarea content + subject content + timestamp.
+	/**
+	 * JSON object to be saved with the textarea content + subject content + timestamp.
+	 * @type {JSON?}
+	 */
 	var item = null;
-	// Event to be used for saving content on demand, when user switches pages.
-	// Note: both the 'pagehide' or 'beforeunload' are deprecated and should not be used.
+
+	/**
+	 * Event name to be used for saving content on demand, when user switches pages.
+	 *
+	 * Note: both the 'pagehide' or 'beforeunload' events are deprecated and should not be used here.
+	 * @const {string}
+	 */
 	const unloadEvent = "visibilitychange";
 
-	// If there's a localStorage entry for the current URL, update the textarea with the saved value.
+	/**
+	 * JSON object describing what we store on the localStorage for each article/message.
+	 * @typedef StoredContent
+	 * @type {object}
+	 * @property {string} subject   - Content of the "subject" input box (also known as "title").
+	 * @property {string} content   - The actual content of the textarea box (the article/message itself).
+	 * @property {number} timestamp - Time in milliseconds since the Unix epoch, to deal with stale content.
+	 */
+
+	// If there's a `localStorage` entry for the current URL, update the textarea with the saved value.
 	item = message.localStorage.getItem(key);
 	if (item) {
+		/**
+		 * JSON representation of one object in the localStorage.
+		 * @type {StoredContent?}
+		 */
 		var data = JSON.parse(item);
+		/** @since 1.1.0 */
 		// Before 1.1.0, 'our' objects did not carry timestamps, so we need to check for them: (gwyneth 20240415)
 		if (data?.timestamp) {
 			// check if data is stale.
@@ -68,23 +115,23 @@
 		} else {
 			// We don't know if the existing data is stale or not, since it comes from pre-1.1.0 times.
 			// So, upgrade object to the new format, i.e. add a timestamp to existing content.
+			/** @type {string} */
 			let tempContent = data?.content ?? "";
+			/** @type {string} */
 			let tempSubject = data?.subject ?? "";
 			message.localStorage.removeItem(key);
 			item = JSON.stringify({ "content": tempContent, "subject": tempSubject, "timestamp": Date.now() });
 			message.localStorage.setItem(key, item);
 		}
 	}
-//
-// 	// Workaround for non-existing Object.hasOwn()
-// 	function isIn(field, obj) {
-// 		if ("hasOwn" in Object) {
-// 			return Object.hasOwn(field, obj);
-// 		}
-// 		return (field in obj);
-// 	}
 
-	// This function will store the current value of the textarea in localStorage (or delete it if the textarea is blank) with a timestamp.
+	/**
+	 * This function will store the current value of the textarea in localStorage (or delete it if the textarea is blank) with a timestamp.
+	 *
+	 * It gets triggered by the "type" events on the input and textarea elements,
+	 * @function updateStorage
+	 * @type EventListener
+	 */
 	function updateStorage() {
 		// Note: if the visibilitychange event is being used, one should check to see if the visibilityState
 		// is 'hidden' or 'visible'; but we're going to save to storage in both cases.
@@ -106,6 +153,7 @@
 	// When the user presses a key just *once* inside the textarea, run the storage function when the page is unloaded.
 	textarea.addEventListener(
 		"keyup",
+		/** @listens keyup */
 		function() {
 			message.addEventListener(unloadEvent, updateStorage);
 			nIntervId = message.setInterval(updateStorage, 10000);
@@ -114,21 +162,26 @@
 	// Same for the subject, I think:
 	subject.addEventListener(
 		"keyup",
+		/** @listens keyup */
 		function() {
 			message.addEventListener(unloadEvent, updateStorage);
 			nIntervId = message.setInterval(updateStorage, 10000);
 		}, { once: true }
 	);
 
 	// When the form is submitted, delete the localStorage key/value pair.
-	textarea.form.addEventListener("submit", function() {
-		// ... except on Preview. We still want to keep the storage around during preview!
-		// Kudos to
-		if (document.activeElement.value != 'Preview') {
-			message.localStorage.removeItem(key);
-			message.removeEventListener(unloadEvent, updateStorage);
-			message.clearInterval(nIntervId);
-			console.debug("Text submitted (not in preview!); removed from localStorage");
+	textarea.form.addEventListener(
+		"submit",
+		/** @listens submit */
+		function() {
+			// ... except on Preview. We still want to keep the storage around during preview!
+			// Kudos to
+			if (document.activeElement.value != 'Preview') {
+				message.localStorage.removeItem(key);
+				message.removeEventListener(unloadEvent, updateStorage);
+				message.clearInterval(nIntervId);
+				console.debug("Text submitted (not in preview!); removed from localStorage");
+			}
 		}
-	});
+	);
 })(this, this.document);