enso-org · mergify · May 19, 2023 · Apr 24, 2023 · Apr 24, 2023 · Apr 25, 2023
@@ -226,6 +226,18 @@ export default [
             ...tsEslint.configs['recommended-requiring-type-checking']?.rules,
             ...tsEslint.configs.strict?.rules,
             eqeqeq: ['error', 'always', { null: 'never' }],
+            'require-jsdoc': [
+                'error',
+                {
+                    require: {
+                        FunctionDeclaration: true,
+                        MethodDefinition: true,
+                        ClassDeclaration: true,
+                        ArrowFunctionExpression: true,
+                        FunctionExpression: true,
+                    },
+                },
+            ],
             'sort-imports': ['error', { allowSeparatedGroups: true }],
             'no-restricted-syntax': ['error', ...RESTRICTED_SYNTAXES],
             'prefer-arrow-callback': 'error',

@@ -75,9 +75,6 @@
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import opener from 'opener'
-
-import * as electron from 'electron'
 
 import * as electron from 'electron'
 import opener from 'opener'

@@ -46,6 +46,7 @@ interface ConfigConfig {
 export class Config {
     dir: string
     port: number
+    /** Creates a server configuration. */
     constructor(cfg: ConfigConfig) {
         this.dir = path.resolve(cfg.dir)
         this.port = cfg.port
@@ -66,12 +67,13 @@ async function findPort(port: number): Promise<number> {
 // === Server ===
 // ==============
 
-/// A simple server implementation.
-///
-/// Initially it was based on `union`, but later we migrated to `create-servers`. Read this topic to
-/// learn why: https://github.com/http-party/http-server/issues/483
+/** A simple server implementation.
+ *
+ * Initially it was based on `union`, but later we migrated to `create-servers`. Read this topic to
+ * learn why: https://github.com/http-party/http-server/issues/483 */
 export class Server {
     server: unknown
+    /** Creates a simple HTTP server. */
     constructor(public config: Config) {}
 
     /** Server constructor. */
@@ -83,6 +85,7 @@ export class Server {
         return server
     }
 
+    /** Starts the server. */
     run(): Promise<void> {
         return new Promise((resolve, reject) => {
             this.server = createServer(
@@ -103,6 +106,7 @@ export class Server {
         })
     }
 
+    /** Responds to an incoming request. */
     process(request: http.IncomingMessage, response: http.ServerResponse) {
         const requestUrl = request.url
         if (requestUrl == null) {

@@ -38,6 +38,8 @@ const USAGE =
     `the application from a web-browser, the creation of a window can be suppressed by ` +
     `entering either '-window=false' or '-no-window'.`
 
+/** Contains information for a category of command line options and the options it is comprised of.
+ */
 class Section<T> {
     description = ''
     entries: (readonly [cmdOption: string, option: config.Option<T>])[] = []
@@ -201,9 +203,12 @@ function wordWrap(str: string, width: number): string[] {
 // === Chrome Options ===
 // ======================
 
+/** Represents a command line option to be passed to the Chrome instance powering Electron. */
 export class ChromeOption {
+    /** Creates a {@link ChromeOption}. */
     constructor(public name: string, public value?: string) {}
 
+    /** Returns the option as it would appear on the command line. */
     display(): string {
         const value = this.value == null ? '' : `=${this.value}`
         return `--${this.name}${value}`
@@ -355,7 +360,8 @@ export function parseArgs(clientArgs: string[] = fileAssociations.CLIENT_ARGUMEN
         windowSize = parsedWindowSize
     }
 
-    const printHelpAndExit = (exitCode?: number) => {
+    /** Prints the entire help text, and exits with the specified exit code. */
+    function printHelpAndExit(exitCode?: number) {
         printHelp({
             args,
             groupsOrdering: [

@@ -89,7 +89,7 @@ function getClientArguments(): string[] {
 // === File Associations ===
 // =========================
 
-/* Check if the given path looks like a file that we can open. */
+/** Check if the given path looks like a file that we can open. */
 export function isFileOpenable(path: string): boolean {
     const extension = pathModule.extname(path).toLowerCase()
     return (
@@ -98,7 +98,7 @@ export function isFileOpenable(path: string): boolean {
     )
 }
 
-/* On macOS when Enso-associated file is opened, the application is first started and then it
+/** On macOS when an Enso-associated file is opened, the application is first started and then it
  * receives the `open-file` event. However, if there is already an instance of Enso running,
  * it receives the `open-file` event (and no new instance is created for us). In this case,
  * we manually start a new instance of the application and pass the file path to it (using the

@@ -44,6 +44,7 @@ class App {
     args: config.Args = config.CONFIG
     isQuitting = false
 
+    /** Initializes and runs the Electron application. */
     async run() {
         urlAssociations.registerAssociations()
         // Register file associations for macOS.
@@ -76,6 +77,7 @@ class App {
         }
     }
 
+    /** Processes the command line arguments. */
     processArguments() {
         // We parse only "client arguments", so we don't have to worry about the Electron-Dev vs
         // Electron-Proper distinction.
@@ -114,14 +116,11 @@ class App {
         }
     }
 
-    /** Set Chrome options based on the app configuration. For comprehensive list of available
+    /** Sets Chrome options based on the app configuration. For comprehensive list of available
      * Chrome options refer to: https://peter.sh/experiments/chromium-command-line-switches. */
     setChromeOptions(chromeOptions: configParser.ChromeOption[]) {
-        const addIf = (
-            opt: contentConfig.Option<boolean>,
-            chromeOptName: string,
-            value?: string
-        ) => {
+        /** Adds the specified Chrome option when the specified command line option is enabled. */
+        function addIf(opt: contentConfig.Option<boolean>, chromeOptName: string, value?: string) {
             if (opt.value) {
                 const chromeOption = new configParser.ChromeOption(chromeOptName, value)
                 const chromeOptionStr = chromeOption.display()
@@ -130,8 +129,10 @@ class App {
                 chromeOptions.push(chromeOption)
             }
         }
-        const add = (option: string, value?: string) =>
+        /** Adds the specified Chrome option. */
+        function add(option: string, value?: string) {
             chromeOptions.push(new configParser.ChromeOption(option, value))
+        }
         logger.groupMeasured('Setting Chrome options', () => {
             const perfOpts = this.args.groups.performance.options
             addIf(perfOpts.disableGpuSandbox, 'disable-gpu-sandbox')
@@ -330,7 +331,8 @@ class App {
         }
     }
 
-    printVersion(): Promise<void> {
+    /** Prints the version of the frontend and the backend. */
+    async printVersion(): Promise<void> {
         const indent = ' '.repeat(utils.INDENT_SIZE)
         let maxNameLen = 0
         for (const name in debug.VERSION_INFO) {
@@ -342,22 +344,20 @@ class App {
             const spacing = ' '.repeat(maxNameLen - name.length)
             console.log(`${indent}${label}:${spacing} ${value}`)
         }
-
         console.log('')
-
         console.log('Backend:')
-        return projectManager.version(this.args).then(backend => {
-            if (!backend) {
-                console.log(`${indent}No backend available.`)
-            } else {
-                const lines = backend.split(/\r?\n/).filter(line => line.length > 0)
-                for (const line of lines) {
-                    console.log(`${indent}${line}`)
-                }
+        const backend = await projectManager.version(this.args)
+        if (!backend) {
+            console.log(`${indent}No backend available.`)
+        } else {
+            const lines = backend.split(/\r?\n/).filter(line => line.length > 0)
+            for (const line of lines) {
+                console.log(`${indent}${line}`)
             }
-        })
+        }
     }
 
+    /** Registers keyboard shortcuts. */
     registerShortcuts() {
         electron.app.on('web-contents-created', (_webContentsCreatedEvent, webContents) => {
             webContents.on('before-input-event', (_beforeInputEvent, input) => {