style: jsdoc comments must be complete sentences

.eslintrc.js

@@ -47,6 +47,7 @@ module.exports = {
 		"@eslint-community/eslint-comments/require-description": "error",
 		"import/no-extraneous-dependencies": "error",
 		"jsdoc/check-syntax": "error",
+		"jsdoc/require-description-complete-sentence": "error",
 		"jsdoc/require-hyphen-before-param-description": "error",
 		"no-multiple-empty-lines": ["error", { max: 1 }],
 		"prefer-destructuring": ["error", { object: true, array: false }],

scripts/license-checker.js

@@ -18,7 +18,7 @@ async function checkLicenses() {
 	console.log("Checking licenses of direct production dependencies...");
 
 	/**
-	 * List of deprecated copyleft license identifiers
+	 * List of deprecated copyleft license identifiers.
 	 * @see {@link https://spdx.org/licenses/#deprecated | SPDX Deprecated License Identifiers}
 	 */
 	const deprecatedLicenseList = [

src/config/index.js

@@ -164,7 +164,7 @@ async function getConfig() {
 				level: env.LOG_LEVEL || "info",
 				/**
 				 * Fastify does not log the req or res body anyway but better
-				 * to be safe as a future change could break it
+				 * to be safe as a future change could break it.
 				 */
 				redact: ["req.body", "req.headers.authorization", "res.body"],
 				serializers: {
@@ -194,7 +194,7 @@ async function getConfig() {
 			/**
 			 * Tesseract OCR's load time is dependent on number of workers
 			 * and languages so is unpredictable. Disable the plugin timeout
-			 * to allow for this
+			 * to allow for this.
 			 */
 			pluginTimeout: env.OCR_ENABLED === true ? 0 : 30000,
 		},

src/plugins/doc-to-txt/index.js

@@ -37,7 +37,7 @@ async function plugin(server) {
 		} catch {
 			/**
 			 * Word-Extractor will throw if the .doc, .docx, .dot, or .dotx file provided
-			 * by client is malformed, thus client error code
+			 * by client is malformed, thus client error code.
 			 */
 			throw server.httpErrors.badRequest();
 		}

src/plugins/doc-to-txt/plugin.test.js

@@ -79,7 +79,7 @@ describe("DOC-to-TXT conversion plugin", () => {
 		expect(response.statusCode).toBe(200);
 	});
 
-	/** @todo use `it.concurrent.each()` once it is no longer experimental */
+	/** @todo Use `it.concurrent.each()` once it is no longer experimental. */
 	it.each([
 		{ testName: "is missing" },
 		{ testName: "is empty", body: Buffer.alloc(0) },

src/plugins/docx-to-html/index.js

@@ -57,7 +57,7 @@ async function plugin(server) {
 		} catch {
 			/**
 			 * Mammoth will throw if the .docm, .docx, .dotm, or .dotx file provided
-			 * by client is malformed, thus client error code
+			 * by client is malformed, thus client error code.
 			 */
 			throw server.httpErrors.badRequest();
 		}

src/plugins/docx-to-html/plugin.test.js

@@ -94,7 +94,7 @@ describe("DOCX-to-HTML conversion plugin", () => {
 		expect(response.statusCode).toBe(200);
 	});
 
-	/** @todo use `it.concurrent.each()` once it is no longer experimental */
+	/** @todo Use `it.concurrent.each()` once it is no longer experimental. */
 	it.each([
 		{ testName: "is missing" },
 		{ testName: "is empty", body: Buffer.alloc(0) },

src/plugins/html-to-txt/index.js

@@ -34,7 +34,7 @@ async function plugin(server) {
 	function htmlToTxt(html) {
 		/**
 		 * `htmlToText` function still attempts to parse empty bodies/input or invalid HTML
-		 * and produces results, so catch them here
+		 * and produces results, so catch them here.
 		 */
 		if (html === undefined || !isHtml(html)) {
 			throw server.httpErrors.badRequest();

src/plugins/html-to-txt/plugin.test.js

@@ -45,7 +45,7 @@ describe("HTML-to-TXT conversion plugin", () => {
 		expect(response.statusCode).toBe(200);
 	});
 
-	/** @todo use `it.concurrent.each()` once it is no longer experimental */
+	/** @todo Use `it.concurrent.each()` once it is no longer experimental. */
 	it.each([
 		{ testName: "is missing" },
 		{ testName: "is empty", body: Buffer.alloc(0) },

src/plugins/image-to-txt/index.js

@@ -9,7 +9,7 @@ const { joinSafe } = require("upath");
  * paths stops Tesseract from repeatedly downloading new trained data and workers
  * from a remote repo, allowing OCR to be used offline.
  * This also stops synchronous read/writes of the trained data,
- * which corrupts the trained data
+ * which corrupts the trained data.
  */
 const workerConfig = {
 	cacheMethod: "readOnly",
@@ -24,7 +24,7 @@ const workerConfig = {
 
 /**
  * Disable HOCR (HTML representation of OCR results) and TSV (tab-separated values)
- * in output, not needed
+ * in output, not needed.
  */
 const workerParams = {
 	tessjs_create_hocr: "0",

src/plugins/pdf-to-html/index.js

@@ -93,7 +93,7 @@ async function plugin(server, options) {
 
 		/**
 		 * Create copy of query string params and prune that,
-		 * as some of the params may be used in other plugins
+		 * as some of the params may be used in other plugins.
 		 */
 		const query = { ...req.query };
 		Object.keys(query).forEach((value) => {
@@ -102,7 +102,7 @@ async function plugin(server, options) {
 			} else {
 				/**
 				 * Convert query string params to literal values to
-				 * allow Poppler module to use them
+				 * allow Poppler module to use them.
 				 */
 				query[value] = parseString(query[value]);
 			}
@@ -115,7 +115,7 @@ async function plugin(server, options) {
 
 		/**
 		 * Create document location object for use by following plugins/hooks
-		 * for clean up and auditing purposes
+		 * for clean up and auditing purposes.
 		 */
 		req.conversionResults.docLocation = {
 			directory,
@@ -133,7 +133,7 @@ async function plugin(server, options) {
 		} catch (err) {
 			/**
 			 * Poppler will throw if the .pdf file provided
-			 * by client is malformed, thus client error code
+			 * by client is malformed, thus client error code.
 			 */
 			if (err.message.includes("Syntax Error:")) {
 				throw server.httpErrors.badRequest();
@@ -146,7 +146,7 @@ async function plugin(server, options) {
 		 * Remove excess title and meta elements created by Poppler
 		 * as it generates a new title and meta element for each page
 		 * of the PDF document.
-		 * Poppler appends `-html` to the file name
+		 * Poppler appends `-html` to the file name.
 		 */
 		const dom = new JSDOM(await readFile(`${tempFile}-html.html`));
 		const titles = dom.window.document.querySelectorAll("title");
@@ -163,7 +163,7 @@ async function plugin(server, options) {
 
 		/**
 		 * Overwrite content of remaining title element with temp file id,
-		 * as Poppler reveals directory structure in title
+		 * as Poppler reveals directory structure in title.
 		 */
 		titles[0].innerHTML = id;
 

src/plugins/pdf-to-html/plugin.test.js

@@ -13,7 +13,7 @@ const getConfig = require("../../config");
 
 /**
  * Used to check that common incorrectly converted Windows-1252
- * to UTF-8 values are removed by the `fix-utf8` module
+ * to UTF-8 values are removed by the `fix-utf8` module.
  */
 const artifacts =
 	/€|â€[šž¦¡°¹˜™œ¢“”]|Æ’|Ë[†œ]|Å[½¡¾¸]|Â[¯·´°]|ï‚·|√|[�Â]|Ã[‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š›œžŸ¡¢£¤¥¦§¨©ª«¬­®¯°±²³´µ¶·¸¹º»¼½¾¿]|â‰[¤¥]|Ã|â€/gu;
@@ -53,7 +53,7 @@ describe("PDF-to-HTML conversion plugin", () => {
 		])
 	);
 
-	/** @todo use `it.concurrent.each()` once it is no longer experimental */
+	/** @todo Use `it.concurrent.each()` once it is no longer experimental. */
 	it.each([
 		{
 			testName: "Converts PDF file to HTML",
@@ -123,7 +123,7 @@ describe("PDF-to-HTML conversion plugin", () => {
 		expect(response.statusCode).toBe(200);
 	});
 
-	/** @todo use `it.concurrent.each()` once it is no longer experimental */
+	/** @todo Use `it.concurrent.each()` once it is no longer experimental. */
 	it.each([
 		{ testName: "is missing" },
 		{ testName: "is empty", body: Buffer.alloc(0) },

src/plugins/pdf-to-txt/index.js

@@ -74,7 +74,7 @@ async function plugin(server, options) {
 
 	/**
 	 * "onSend" hook used instead of "onResponse" ensures
-	 * cancelled request temp data is also removed
+	 * cancelled request temp data is also removed.
 	 */
 	server.addHook("onSend", async (req, _res, payload) => {
 		if (req.conversionResults?.docLocation) {
@@ -95,7 +95,7 @@ async function plugin(server, options) {
 	server.addHook("preHandler", async (req, res) => {
 		/**
 		 * `pdfToText` Poppler function still attempts to parse empty bodies/input
-		 * and produces results, so catch them here
+		 * and produces results, so catch them here.
 		 */
 		if (!req.body || Buffer.byteLength(req.body) === 0) {
 			throw server.httpErrors.badRequest();
@@ -111,7 +111,7 @@ async function plugin(server, options) {
 		/**
 		 * Create copy of query string params and convert query string params to literal
 		 * values to allow Poppler module to use them, as some of the params may be used
-		 * in other plugins
+		 * in other plugins.
 		 */
 		const query = { ...req.query };
 		Object.keys(query).forEach((value) => {
@@ -122,8 +122,8 @@ async function plugin(server, options) {
 
 		/**
 		 * If `ocr` query string param passed then use pdfToCairo and Tesseract OCR engine.
-		 * image-to-txt plugin adds the "tesseract" decorator to server instance,
-		 * if this is missing then OCR is not supported
+		 * Image-to-txt plugin adds the "tesseract" decorator to server instance,
+		 * if this is missing then OCR is not supported.
 		 */
 		if (query.ocr === true && server.tesseract) {
 			// Prune params that pdfToCairo cannot accept
@@ -138,7 +138,7 @@ async function plugin(server, options) {
 
 			/**
 			 * Create document location object for use by following plugins/hooks
-			 * for clean up and auditing purposes
+			 * for clean up and auditing purposes.
 			 */
 			req.conversionResults.docLocation = {
 				directory,
@@ -155,7 +155,7 @@ async function plugin(server, options) {
 			} catch (err) {
 				/**
 				 * Poppler will throw if the .pdf file provided
-				 * by client is malformed, thus client error code
+				 * by client is malformed, thus client error code.
 				 */
 				if (err.message.includes("Syntax Error:")) {
 					throw server.httpErrors.badRequest();
@@ -171,7 +171,7 @@ async function plugin(server, options) {
 				files
 					/**
 					 * Sort files alphabetically to ensure order is maintained,
-					 * as glob does not guarantee order
+					 * as glob does not guarantee order.
 					 */
 					.sort((a, b) => a.localeCompare(b))
 					.map((file) =>
@@ -201,7 +201,7 @@ async function plugin(server, options) {
 			} catch (err) {
 				/**
 				 * Poppler will throw if the .pdf file provided
-				 * by client is malformed, thus client error code
+				 * by client is malformed, thus client error code.
 				 */
 				if (err.message.includes("Syntax Error:")) {
 					throw server.httpErrors.badRequest();

src/plugins/pdf-to-txt/plugin.test.js

@@ -50,7 +50,7 @@ describe("PDF-to-TXT conversion plugin", () => {
 		])
 	);
 
-	/** @todo use `it.concurrent.each()` once it is no longer experimental */
+	/** @todo Use `it.concurrent.each()` once it is no longer experimental. */
 	it.each([
 		{ testName: "Converts PDF file to TXT" },
 		{
@@ -84,8 +84,8 @@ describe("PDF-to-TXT conversion plugin", () => {
 	});
 
 	/**
-	 * OCR tests that use pdftocairo and tesseract
-	 * @todo use `it.concurrent.each()` once it is no longer experimental
+	 * OCR tests that use pdftocairo and tesseract.
+	 * @todo Use `it.concurrent.each()` once it is no longer experimental.
 	 */
 	it.each([
 		{
@@ -176,7 +176,7 @@ describe("PDF-to-TXT conversion plugin", () => {
 		expect(response.statusCode).toBe(200);
 	});
 
-	/** @todo use `it.concurrent.each()` once it is no longer experimental */
+	/** @todo Use `it.concurrent.each()` once it is no longer experimental. */
 	it.each([
 		{ testName: "is missing" },
 		{ testName: "is empty", body: Buffer.alloc(0) },
@@ -214,7 +214,7 @@ describe("PDF-to-TXT conversion plugin", () => {
 		}
 	);
 
-	/** @todo use `it.concurrent.each()` once it is no longer experimental */
+	/** @todo Use `it.concurrent.each()` once it is no longer experimental. */
 	it.each([
 		{
 			testName: "poppler.pdfToText()",

src/plugins/rtf-to-html/index.js

@@ -46,7 +46,7 @@ async function plugin(server, options) {
 
 	/**
 	 * "onSend" hook used instead of "onResponse" ensures
-	 * cancelled request temp data is also removed
+	 * cancelled request temp data is also removed.
 	 */
 	server.addHook("onSend", async (req, _res, payload) => {
 		if (req.conversionResults?.docLocation) {
@@ -75,7 +75,7 @@ async function plugin(server, options) {
 				 * would overwrite the first request's image and that image would be embedded
 				 * into both HTML documents.
 				 *
-				 * We wouldn't want to add one patient's image to another patient's document
+				 * We wouldn't want to add one patient's image to another patient's document.
 				 */
 				noPictures: true,
 				outputHtml: true,
@@ -87,7 +87,7 @@ async function plugin(server, options) {
 		/**
 		 * UnRTF removes hyperlinks and replaces them with the text of the hyperlink,
 		 * however older versions of UnRTF remove the hyperlink text entirely.
-		 * Remove RTF hyperlinks prior to conversion to ensure consistent results
+		 * Remove RTF hyperlinks prior to conversion to ensure consistent results.
 		 */
 		req.body = req.body.toString().replace(rtfHyperLinkRegex, "$1");
 
@@ -102,7 +102,7 @@ async function plugin(server, options) {
 
 		/**
 		 * Create document location object for use by following plugins/hooks
-		 * for clean up and auditing purposes
+		 * for clean up and auditing purposes.
 		 */
 		req.conversionResults.docLocation = {
 			directory,
@@ -129,7 +129,7 @@ async function plugin(server, options) {
 			 * UnRTF generates the image name as `pict001.wmf`, `pict002.wmf`, and so on.
 			 * This means files can be safely removed from the cwd without running the
 			 * risk of removing any important files such as `package.json`, should an image
-			 * ever have the same name
+			 * ever have the same name.
 			 */
 			const images = dom.window.document.querySelectorAll("img");
 			/* istanbul ignore next: dependant on UnRTF version used */
@@ -141,7 +141,7 @@ async function plugin(server, options) {
 						/**
 						 * `rm()` used instead of `unlink()` because concurrent requests may create duplicate files,
 						 * which could cause `unlink()` to throw an ENOENT error if the file has already been removed
-						 * by another request's call of this hook
+						 * by another request's call of this hook.
 						 */
 						return rm(joinSafe(process.cwd(), src), {
 							force: true,
@@ -162,7 +162,7 @@ async function plugin(server, options) {
 		} catch (err) {
 			/**
 			 * UnRTF will throw if the .rtf file provided
-			 * by client is malformed, thus client error code
+			 * by client is malformed, thus client error code.
 			 */
 			if (err.message.includes("File is not the correct media type")) {
 				throw server.httpErrors.badRequest();