Tools: Apply eslint rule multiline-comment-style with checkJSDoc option

.eslintrc.js

@@ -137,7 +137,7 @@ module.exports = {
 			'named': 'never',
 			'asyncArrow': 'always',
 		}],
-		'multiline-comment-style': ['error', 'separate-lines'],
+		'multiline-comment-style': ['error', 'separate-lines', { checkJSDoc: true }],
 		'space-before-blocks': 'error',
 		'spaced-comment': ['error', 'always'],
 		'keyword-spacing': ['error', { 'before': true, 'after': true }],
@@ -183,7 +183,7 @@ module.exports = {
 				'project': './tsconfig.eslint.json',
 			},
 			'rules': {
-				'github/array-foreach': ['error'],
+
 				'@typescript-eslint/explicit-member-accessibility': ['error'],
 				'@typescript-eslint/type-annotation-spacing': ['error', { 'before': false, 'after': true }],
 				'@typescript-eslint/array-type': 'error',

packages/app-clipper/popup/config/modules.js

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 'use strict';
 
 const fs = require('fs');

packages/app-mobile/components/NoteEditor/CodeMirror/CodeMirror.test.ts

@@ -1,7 +1,8 @@
+/* eslint-disable multiline-comment-style */
 /**
  * @jest-environment jsdom
  */
-
+/* eslint-enable multiline-comment-style */
 
 import { EditorSettings } from '../types';
 import { initCodeMirror } from './CodeMirror';

packages/app-mobile/components/NoteEditor/CodeMirror/markdownCommands.bulletedVsChecklist.test.ts

@@ -1,6 +1,8 @@
+/* eslint-disable multiline-comment-style */
 /**
  * @jest-environment jsdom
  */
+/* eslint-enable multiline-comment-style */
 import { EditorSelection } from '@codemirror/state';
 import { ListType } from '../types';
 import createEditor from './testUtil/createEditor';

packages/app-mobile/components/NoteEditor/CodeMirror/markdownCommands.test.ts

@@ -1,6 +1,8 @@
+/* eslint-disable multiline-comment-style */
 /**
  * @jest-environment jsdom
  */
+/* eslint-enable multiline-comment-style */
 
 import { EditorSelection } from '@codemirror/state';
 import {

packages/app-mobile/components/NoteEditor/CodeMirror/markdownCommands.toggleList.test.ts

@@ -1,6 +1,8 @@
+/* eslint-disable multiline-comment-style */
 /**
  * @jest-environment jsdom
  */
+/* eslint-enable multiline-comment-style */
 
 import { EditorSelection, EditorState } from '@codemirror/state';
 import {

packages/app-mobile/components/NoteEditor/CodeMirror/markdownMathParser.test.ts

@@ -1,6 +1,8 @@
+/* eslint-disable multiline-comment-style */
 /**
  * @jest-environment jsdom
  */
+/* eslint-enable multiline-comment-style */
 
 import { syntaxTree } from '@codemirror/language';
 import { SyntaxNode } from '@lezer/common';

packages/app-mobile/components/NoteEditor/CodeMirror/markdownMathParser.ts

@@ -1,9 +1,7 @@
-/**
+// Search for $s and $$s in markdown and mark the regions between them as math.
- * Search for $s and $$s in markdown and mark the regions between them as math.
+//
- *
+// Text between single $s is marked as InlineMath and text between $$s is marked
- * Text between single $s is marked as InlineMath and text between $$s is marked
+// as BlockMath.
- * as BlockMath.
- */
 
 import { tags, Tag } from '@lezer/highlight';
 import { parseMixed, SyntaxNodeRef, Input, NestedParse, ParseWrapper } from '@lezer/common';
@@ -34,13 +32,11 @@ export const inlineMathContentTagName = 'InlineMathContent';
 export const mathTag = Tag.define(tags.monospace);
 export const inlineMathTag = Tag.define(mathTag);
 
-/**
+// Wraps a TeX math-mode parser. This removes [nodeTag] from the syntax tree
- * Wraps a TeX math-mode parser. This removes [nodeTag] from the syntax tree
+// and replaces it with a region handled by the sTeXMath parser.
- * and replaces it with a region handled by the sTeXMath parser.
+//
- *
+// @param nodeTag Name of the nodes to replace with regions parsed by the sTeX parser.
- * @param nodeTag Name of the nodes to replace with regions parsed by the sTeX parser.
+// @returns a wrapped sTeX parser.
- * @returns a wrapped sTeX parser.
- */
 const wrappedTeXParser = (nodeTag: string): ParseWrapper => {
 	return parseMixed((node: SyntaxNodeRef, _input: Input): NestedParse => {
 		if (node.name !== nodeTag) {

packages/app-mobile/metro.config.js

@@ -1,9 +1,5 @@
-/**
+// Metro configuration for React Native
- * Metro configuration for React Native
+// https://github.com/facebook/react-native
- * https://github.com/facebook/react-native
- *
- * @format
- */
 
 // The technique below to get the symlinked packages to work with the Metro
 // bundler comes from this comment:

packages/app-mobile/utils/ShareUtils.ts

@@ -6,9 +6,7 @@ import { CachesDirectoryPath } from 'react-native-fs';
 // when refactoring this name, make sure to refactor the `SharePackage.java` (in android) as well
 const DIR_NAME = 'sharedFiles';
 
-/**
+// Copy a file to be shared to cache, renaming it to its orignal name
- * Copy a file to be shared to cache, renaming it to its orignal name
- */
 export async function copyToCache(resource: ResourceEntity): Promise<string> {
 	const filename = Resource.friendlySafeFilename(resource);
 
@@ -22,9 +20,7 @@ export async function copyToCache(resource: ResourceEntity): Promise<string> {
 	return targetFile;
 }
 
-/**
+// Clear previously shared files from cache
- * Clear previously shared files from cache
- */
 export async function clearSharedFilesCache(): Promise<void> {
 	return shim.fsDriver().remove(`${CachesDirectoryPath}/sharedFiles`);
 }

packages/lib/import-enex-html-gen.test.js

@@ -28,17 +28,15 @@ const beautifyHtml = (html) => {
 	});
 };
 
-/**
+// Tests the importer for a single note, checking that the result of
- * Tests the importer for a single note, checking that the result of
+// processing the given `.enex` input file matches the contents of the given
- * processing the given `.enex` input file matches the contents of the given
+// `.html` file.
- * `.html` file.
+//
- *
+// Note that this does not test the importing of an entire exported `.enex`
- * Note that this does not test the importing of an entire exported `.enex`
+// archive, but rather a single node of such a file. Thus, the test data files
- * archive, but rather a single node of such a file. Thus, the test data files
+// (e.g. `./enex_to_html/code1.enex`) correspond to the contents of a single
- * (e.g. `./enex_to_html/code1.enex`) correspond to the contents of a single
+// `<note>...</note>` node in an `.enex` file already extracted from
- * `<note>...</note>` node in an `.enex` file already extracted from
+// `<content><![CDATA[...]]</content>`.
- * `<content><![CDATA[...]]</content>`.
- */
 const compareOutputToExpected = (options) => {
 	options = {
 		resources: [],

packages/lib/services/interop/InteropService.ts

@@ -196,13 +196,11 @@ export default class InteropService {
 		}
 	}
 
-	/**
+	// NOTE TO FUTURE SELF: It might make sense to simply move all the existing
-	 * NOTE TO FUTURE SELF: It might make sense to simply move all the existing
+	// formatters to the `newModuleFromPath_` approach, so that there's only one way
-	 * formatters to the `newModuleFromPath_` approach, so that there's only one way
+	// to do this mapping. This isn't a priority right now (per the convo in:
-	 * to do this mapping. This isn't a priority right now (per the convo in:
+	// https://github.com/laurent22/joplin/pull/1795#discussion_r322379121) but
-	 * https://github.com/laurent22/joplin/pull/1795#discussion_r322379121) but
+	// we can do it if it ever becomes necessary.
-	 * we can do it if it ever becomes necessary.
-	 */
 	private newModuleByFormat_(type: ModuleType, format: string, outputFormat: ImportModuleOutputFormat = ImportModuleOutputFormat.Markdown) {
 		const moduleMetadata = this.findModuleByFormat_(type, format, null, outputFormat);
 		if (!moduleMetadata) throw new Error(_('Cannot load "%s" module for format "%s" and output "%s"', type, format, outputFormat));
@@ -221,14 +219,12 @@ export default class InteropService {
 		return output;
 	}
 
-	/**
+	// The existing `newModuleByFormat_` fn would load by the input format. This
-	 * The existing `newModuleByFormat_` fn would load by the input format. This
+	// was fine when there was a 1-1 mapping of input formats to output formats,
-	 * was fine when there was a 1-1 mapping of input formats to output formats,
+	// but now that we have 2 possible outputs for an `enex` input, we need to be
-	 * but now that we have 2 possible outputs for an `enex` input, we need to be
+	// explicit with which importer we want to use.
-	 * explicit with which importer we want to use.
+	//
-	 *
+	// https://github.com/laurent22/joplin/pull/1795#pullrequestreview-281574417
-	 * https://github.com/laurent22/joplin/pull/1795#pullrequestreview-281574417
-	 */
 	private newModuleFromPath_(type: ModuleType, options: any) {
 		const moduleMetadata = this.findModuleByFormat_(type, options.format, options.target);
 		if (!moduleMetadata) throw new Error(_('Cannot load "%s" module for format "%s" and target "%s"', type, options.format, options.target));

packages/lib/services/interop/InteropService_Importer_Md.ts

@@ -90,10 +90,8 @@ export default class InteropService_Importer_Md extends InteropService_Importer_
 		return splitted.join('#');
 	}
 
-	/**
+	// Parse text for links, attempt to find local file, if found create Joplin resource
-	 * Parse text for links, attempt to find local file, if found create Joplin resource
+	// and update link accordingly.
-	 * and update link accordingly.
-	 */
 	public async importLocalFiles(filePath: string, md: string, parentFolderId: string) {
 		let updated = md;
 		const markdownLinks = markdownUtils.extractFileUrls(md);

packages/lib/services/plugins/api/Global.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import Plugin from '../Plugin';
 import Joplin from './Joplin';
 

packages/lib/services/plugins/api/Joplin.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import Plugin from '../Plugin';
 import JoplinData from './JoplinData';
 import JoplinPlugins from './JoplinPlugins';

packages/lib/services/plugins/api/JoplinClipboard.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 export default class JoplinClipboard {
 
 	private electronClipboard_: any = null;

packages/lib/services/plugins/api/JoplinCommands.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import CommandService, { CommandContext, CommandDeclaration, CommandRuntime } from '../../CommandService';
 import { Command } from './types';
 

packages/lib/services/plugins/api/JoplinContentScripts.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import Plugin from '../Plugin';
 import { ContentScriptType } from './types';
 

packages/lib/services/plugins/api/JoplinData.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import { ModelType } from '../../../BaseModel';
 import BaseItem from '../../../models/BaseItem';
 import Resource from '../../../models/Resource';

packages/lib/services/plugins/api/JoplinFilters.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import eventManager from '../../../eventManager';
 
 /**

packages/lib/services/plugins/api/JoplinInterop.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import InteropService from '../../interop/InteropService';
 import { Module, ModuleType } from '../../interop/types';
 import { ExportModule, ImportModule } from './types';

packages/lib/services/plugins/api/JoplinPlugins.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import Plugin from '../Plugin';
 import Logger from '../../../Logger';
 import { ContentScriptType, Script } from './types';

packages/lib/services/plugins/api/JoplinSettings.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import eventManager from '../../../eventManager';
 import Setting, { SettingItem as InternalSettingItem, SettingSectionSource } from '../../../models/Setting';
 import Plugin from '../Plugin';

packages/lib/services/plugins/api/JoplinViews.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import Plugin from '../Plugin';
 import JoplinViewsDialogs from './JoplinViewsDialogs';
 import JoplinViewsMenuItems from './JoplinViewsMenuItems';

packages/lib/services/plugins/api/JoplinViewsDialogs.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import Plugin from '../Plugin';
 import createViewHandle from '../utils/createViewHandle';
 import WebviewController, { ContainerType } from '../WebviewController';

packages/lib/services/plugins/api/JoplinViewsMenuItems.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import KeymapService from '../../KeymapService';
 import { CreateMenuItemOptions, MenuItemLocation } from './types';
 import MenuItemController from '../MenuItemController';

packages/lib/services/plugins/api/JoplinViewsMenus.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import KeymapService from '../../KeymapService';
 import { MenuItem, MenuItemLocation } from './types';
 import MenuController from '../MenuController';

packages/lib/services/plugins/api/JoplinViewsPanels.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import Plugin from '../Plugin';
 import createViewHandle from '../utils/createViewHandle';
 import WebviewController, { ContainerType } from '../WebviewController';

packages/lib/services/plugins/api/JoplinViewsToolbarButtons.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import { ToolbarButtonLocation } from './types';
 import Plugin from '../Plugin';
 import ToolbarButtonController from '../ToolbarButtonController';

packages/lib/services/plugins/api/JoplinWindow.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import Plugin from '../Plugin';
 import * as fs from 'fs-extra';
 

packages/lib/services/plugins/api/JoplinWorkspace.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 import { ModelType } from '../../../BaseModel';
 import eventManager from '../../../eventManager';
 import Setting from '../../../models/Setting';

packages/lib/services/plugins/api/types.ts

@@ -1,3 +1,5 @@
+/* eslint-disable multiline-comment-style */
+
 // =================================================================
 // Command API types
 // =================================================================

packages/react-native-saf-x/src/index.ts

@@ -92,10 +92,8 @@ export type CreateDocumentOptions = FileOperationOptions & {
   initialName?: string;
 };
 
-/**
+// Open the Document Picker to select a folder. Read/Write Permission will be granted to the selected folder.
- * Open the Document Picker to select a folder. Read/Write Permission will be granted to the selected folder.
+// Returns an object of type `DocumentFileDetail` or `null` if user did not select a folder.
- * Returns an object of type `DocumentFileDetail` or `null` if user did not select a folder.
- */
 export function openDocumentTree(persist: boolean) {
 	return SafX.openDocumentTree(persist);
 }
@@ -107,20 +105,16 @@ export type OpenDocumentOptions = {
   multiple?: boolean;
 };
 
-/**
+// Open the Document Picker to select a file.
- * Open the Document Picker to select a file.
+// DocumentFileDetail is always an array.
- * DocumentFileDetail is always an array.
+// @returns `DocumentFileDetail[]` or `null` if user did not select a file.
- * @returns `DocumentFileDetail[]` or `null` if user did not select a file.
- */
 export function openDocument(options: OpenDocumentOptions) {
 	const { persist = false, multiple = false } = options;
 	return SafX.openDocument(persist, multiple);
 }
 
-/**
+// Open the Document Picker to save a file.
- * Open the Document Picker to save a file.
+// Returns an object of type `DocumentFileDetail` or `null` if user did not select a file.
- * Returns an object of type `DocumentFileDetail` or `null` if user did not select a file.
- */
 export function createDocument(data: string, options?: CreateDocumentOptions) {
 	if (!options) options = {};
 	const { encoding, initialName, mimeType } = options;
@@ -147,11 +141,9 @@ export function readFile(
 	return SafX.readFile(uriString, encoding);
 }
 
-/**
+// Writes the given data to the file at given uri.
- * Writes the given data to the file at given uri.
+// Tries to create the file if does not already exist before writing to it.
- * Tries to create the file if does not already exist before writing to it.
+// Resolves with given uriString if successful.
- * Resolves with given uriString if successful.
- */
 export function writeFile(
 	uriString: string,
 	data: string,
@@ -162,10 +154,8 @@ export function writeFile(
 	return SafX.writeFile(uriString, data, encoding, mimeType, !!append);
 }
 
-/**
+// Creates an empty file at given uri.
- * Creates an empty file at given uri.
+// Rejects if a file or directory exist at given uri.
- * Rejects if a file or directory exist at given uri.
- */
 export function createFile(
 	uriString: string,
 	options?: Pick<FileOperationOptions, 'mimeType'>
@@ -175,29 +165,23 @@ export function createFile(
 	return SafX.createFile(uriString, mimeType);
 }
 
-/**
+// Removes the file or directory at given uri.
- * Removes the file or directory at given uri.
+// Resolves with `true` if delete is successful, throws otherwise.
- * Resolves with `true` if delete is successful, throws otherwise.
- */
 export function unlink(uriString: string) {
 	return SafX.unlink(uriString);
 }
 
-/**
+// Create a directory at given uri.
- * Create a directory at given uri.
+// Automatically creates folders in path if needed.
- * Automatically creates folders in path if needed.
+// You can use it to create nested directories easily.
- * You can use it to create nested directories easily.
+// Rejects if it fails.
- * Rejects if it fails.
- */
 export function mkdir(uriString: string) {
 	return SafX.mkdir(uriString);
 }
 
-/**
+// Renames the document at given uri.
- * Renames the document at given uri.
+// uri can be file or folder.
- * uri can be file or folder.
+// Resolves with `true` if successful and `false` otherwise.
- * Resolves with `true` if successful and `false` otherwise.
- */
 export function rename(uriString: string, newName: string) {
 	return SafX.rename(uriString, newName);
 }
@@ -226,11 +210,9 @@ type FileTransferOptions = {
   replaceIfDestinationExists?: boolean;
 };
 
-/**
+// Copy file from source uri to destination uri.
- * Copy file from source uri to destination uri.
+// promise Rejects if destination already exists and `replaceIfDestinationExists` option is not set to true.
- * promise Rejects if destination already exists and `replaceIfDestinationExists` option is not set to true.
+// Does not support moving directories.
- * Does not support moving directories.
- */
 export function copyFile(
 	srcUri: string,
 	destUri: string,
@@ -241,11 +223,9 @@ export function copyFile(
 	return SafX.transferFile(srcUri, destUri, replaceIfDestinationExists, true);
 }
 
-/**
+// Move file from source uri to destination uri.
- * Move file from source uri to destination uri.
+// promise Rejects if destination already exists and `replaceIfDestinationExists` option is not set to true.
- * promise Rejects if destination already exists and `replaceIfDestinationExists` option is not set to true.
+// Does not support moving directories.
- * Does not support moving directories.
- */
 export function moveFile(
 	srcUri: string,
 	destUri: string,

packages/renderer/MdToHtml/createEventHandlingAttrs.test.ts

@@ -1,6 +1,8 @@
+/* eslint-disable multiline-comment-style */
 /**
  * @jest-environment jsdom
  */
+/* eslint-enable multiline-comment-style */
 
 import { createEventHandlingListeners, Options } from './createEventHandlingAttrs';
 import { describe, beforeAll, it, jest, expect } from '@jest/globals';