docs: add JSDoc for some exports @W-13278716 (#4014)

* chore: add temp file for tracking all exports * docs(shared): add jsdoc for language features * chore: missed an export * docs(exports): add jsdoc for @lwc/shared language features * style: add eslint-plugin-jsdoc * chore: eslint-plugin-jsdoc auto fixes * chore(linter): manual fixes for jsdoc rules * chore: simplify env config for test files * style(jsdoc): enforce documenting yields * docs: include @param in all jsdocs, but not descriptions (yet) * docs(exports): fully document all @lwc/shared language features * chore: remove temp file * chore: lint JSDoc in @lwc/shared * chore(eslint): suppress unimportant warnings * docs(rollup-plugin): add jsdoc for main export * fix: use JSDoc comment instead of plain multiline * docs(babel-plugin-component): polish JSDoc for main plugin export * chore: mark progress in .eslintrc * docs(wire-service): polish JSDoc for `register` * docs(errors): add JSDoc for @lwc/errors * docs(errors): polish JSDoc for @lwc/features * chore: mark @lwc/style-compiler as documented It has no top-level exports, easy! * docs(template-compiler): add bad JSDoc for top-level exports * chore(jsdoc): comment block is not jsdoc * chore: revert jsdoc changes to 3rd party files * chore(eslint): enforce stricter JSDoc rules * docs: improve JSDoc in root scripts * chore(eslint): auto-fixes for new JSDoc rules * chore(eslint): manual for new JSDoc rules * chore: fix bad merge * docs: manual JSDoc tweaks post-merge * docs(style-compiler): add JSDoc for top-level exports * chore: mark style-compiler as complete * docs(style-compiler): use correct name in README * revert: remove useless empty JSDoc * revert: don't JSDoc 3rd party * docs(module-resolver): add JSDoc for main export * revert: accidental JSDocification of __PURE__ annotations * Update packages/@lwc/errors/src/compiler/utils.ts Co-authored-by: Eugene Kashida <[email protected]> --------- Co-authored-by: Eugene Kashida <[email protected]>
salesforce · Feb 27, 2024 · 36775f2 · 36775f2
1 parent 64e9b91
commit 36775f2
Show file tree

Hide file tree

Showing 17 changed files with 155 additions and 36 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -313,20 +313,18 @@
                 "packages/@lwc/perf-benchmarks-components/**",
                 "packages/@lwc/perf-benchmarks/**",
                 // TODO [W-13278716]: All top-level exports should have JSDOC enforced
-                "packages/@lwc/babel-plugin-component/**",
                 "packages/@lwc/compiler/**",
                 "packages/@lwc/engine-core/**",
                 "packages/@lwc/engine-dom/**",
                 "packages/@lwc/engine-server/**",
-                "packages/@lwc/errors/**",
-                "packages/@lwc/features/**",
+                // Package-level exports are documented, but not all file-level exports are, so we
+                // should keep these disabled for now
+                "packages/@lwc/babel-plugin-component/**",
                 "packages/@lwc/module-resolver/**",
-                "packages/@lwc/rollup-plugin/**",
                 "packages/@lwc/shared/**",
                 "packages/@lwc/style-compiler/**",
                 "packages/@lwc/synthetic-shadow/**",
-                "packages/@lwc/template-compiler/**",
-                "packages/@lwc/wire-service/**"
+                "packages/@lwc/template-compiler/**"
             ],
             "rules": {
                 "jsdoc/require-jsdoc": "off",
@@ -337,6 +335,19 @@
                 "jsdoc/require-returns": "off",
                 "jsdoc/require-throws": "off"
             }
+        },
+        // TODO [W-13278716]: Not everything *needs* an example, so I'll probably disable the rule
+        // when the ticket is complete, but for now I want to enable by default and disable as I go.
+        {
+            "files": [
+                "packages/@lwc/babel-plugin-component/**",
+                "packages/@lwc/errors/**",
+                "packages/@lwc/rollup-plugin/**",
+                "packages/@lwc/wire-service/**"
+            ],
+            "rules": {
+                "jsdoc/require-example": "off"
+            }
         }
     ]
 }
diff --git a/packages/@lwc/babel-plugin-component/src/dynamic-imports.ts b/packages/@lwc/babel-plugin-component/src/dynamic-imports.ts
@@ -28,7 +28,7 @@ function validateImport(sourcePath: NodePath<types.Node>, state: LwcBabelPluginP
     }
 }
 
-/*
+/**
  * Expected API for this plugin:
  * { dynamicImports: { loader: string, strictSpecifier: boolean } }
  */

diff --git a/packages/@lwc/errors/src/compiler/errors.ts b/packages/@lwc/errors/src/compiler/errors.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -25,6 +25,12 @@ export interface ErrorConfig {
     origin?: CompilerDiagnosticOrigin;
 }
 
+/**
+ * Generates a friendly error message for the given error type, using the provided template values.
+ * @param errorInfo The object holding the error metadata.
+ * @param args Values used to fill the error message template.
+ * @returns The generated error message.
+ */
 export function generateErrorMessage(errorInfo: LWCErrorInfo, args?: any[]): string {
     const message = Array.isArray(args)
         ? templateString(errorInfo.message, args)
@@ -43,6 +49,7 @@ export function generateErrorMessage(errorInfo: LWCErrorInfo, args?: any[]): str
  * info about the error's code and its origin (filename, line, column) when applicable.
  * @param errorInfo The object holding the error metadata.
  * @param config A config object providing any message arguments and origin info needed to create the error.
+ * @returns The generated compiler diagnostic object.
  */
 export function generateCompilerDiagnostic(
     errorInfo: LWCErrorInfo,
@@ -69,6 +76,7 @@ export function generateCompilerDiagnostic(
  * the error's code and its origin (filename, line, column) when applicable.
  * @param errorInfo The object holding the error metadata.
  * @param config A config object providing any message arguments and origin info needed to create the error.
+ * @returns The generated compiler error.
  */
 export function generateCompilerError(
     errorInfo: LWCErrorInfo,
@@ -85,6 +93,13 @@ export function generateCompilerError(
     return error;
 }
 
+/**
+ * Validates that the provided condition is truthy.
+ * @param condition Condition to check.
+ * @param errorInfo The object holding the error metadata.
+ * @param args Values used to fill the error message template.
+ * @throws Throws a compiler error if the provided condition is falsy.
+ */
 export function invariant(condition: boolean, errorInfo: LWCErrorInfo, args?: any[]) {
     if (!condition) {
         throw generateCompilerError(errorInfo, {
@@ -95,9 +110,10 @@ export function invariant(condition: boolean, errorInfo: LWCErrorInfo, args?: an
 
 /**
  * Normalizes a received error into a CompilerError. Adds any provided additional origin info.
- * @param errorInfo
- * @param error
- * @param origin
+ * @param errorInfo The object holding the error metadata.
+ * @param error The original error.
+ * @param origin The origin associated with the error.
+ * @returns The normalized compiler error.
  */
 export function normalizeToCompilerError(
     errorInfo: LWCErrorInfo,
@@ -125,9 +141,10 @@ export function normalizeToCompilerError(
 
 /**
  * Normalizes a received error into a CompilerDiagnostic. Adds any provided additional origin info.
- * @param errorInfo
- * @param error
- * @param origin
+ * @param errorInfo The object holding the error metadata.
+ * @param error The original error.
+ * @param origin The origin of the error.
+ * @returns The normalized compiler diagnostic object.
  */
 export function normalizeToDiagnostic(
     errorInfo: LWCErrorInfo,

diff --git a/packages/@lwc/errors/src/compiler/utils.ts b/packages/@lwc/errors/src/compiler/utils.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -58,6 +58,11 @@ export class CompilerError extends Error implements CompilerDiagnostic {
     }
 }
 
+/**
+ * Extracts an error code from the given error.
+ * @param error The error to check.
+ * @returns The error code, if found.
+ */
 export function getCodeFromError(error: any): number | undefined {
     if (error.lwcCode && typeof error.lwcCode === 'number') {
         return error.lwcCode;
@@ -67,6 +72,13 @@ export function getCodeFromError(error: any): number | undefined {
     return undefined;
 }
 
+/**
+ * Extracts the filename from the provided parameters, preferring to use the compiler diagnostic
+ * origin, if provided.
+ * @param origin Compiler diagnositic origin data
+ * @param obj Any object that might have a filename associated
+ * @returns The filename, if found.
+ */
 export function getFilename(
     origin: CompilerDiagnosticOrigin | undefined,
     obj?: any
@@ -80,6 +92,13 @@ export function getFilename(
     return undefined;
 }
 
+/**
+ * Extracts the location from the provided parameters, preferring to use the compiler diagnostic
+ * origin, if provided.
+ * @param origin Compiler diagnositic origin data
+ * @param obj Any object that might have a location property
+ * @returns The location, if found.
+ */
 export function getLocation(
     origin: CompilerDiagnosticOrigin | undefined,
     obj?: any

diff --git a/packages/@lwc/errors/src/shared/utils.ts b/packages/@lwc/errors/src/shared/utils.ts
@@ -1,10 +1,16 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 const templateRegex = /\{([0-9]+)\}/g;
+/**
+ * Replaces {0} in the given string with the value from the given array
+ * @param template Template string to fill
+ * @param args Values to fill with
+ * @returns Filled string
+ */
 export function templateString(template: string, args: any[]) {
     return template.replace(templateRegex, (_, index) => {
         return args[index];

diff --git a/packages/@lwc/features/src/index.ts b/packages/@lwc/features/src/index.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -31,8 +31,10 @@ const flags: Partial<FeatureFlagMap> = (globalThis as any).lwcRuntimeFlags;
 /**
  * Set the value at runtime of a given feature flag. This method only be invoked once per feature
  * flag. It is meant to be used during the app initialization.
- * @param name
- * @param value
+ * @param name Name of the feature flag to set
+ * @param value Whether the feature flag should be enabled
+ * @throws Will throw if a non-boolean value is provided when running in production.
+ * @example setFeatureFlag("DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE", true)
  */
 export function setFeatureFlag(name: FeatureFlagName, value: FeatureFlagValue): void {
     if (!isBoolean(value)) {
@@ -73,8 +75,9 @@ export function setFeatureFlag(name: FeatureFlagName, value: FeatureFlagValue):
 /**
  * Set the value at runtime of a given feature flag. This method should only be used for testing
  * purposes. It is a no-op when invoked in production mode.
- * @param name
- * @param value
+ * @param name Name of the feature flag to enable or disable
+ * @param value Whether the feature flag should be enabled
+ * @example setFeatureFlag("DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE", true)
  */
 export function setFeatureFlagForTest(name: FeatureFlagName, value: FeatureFlagValue): void {
     // This may seem redundant, but `process.env.NODE_ENV === 'test-karma-lwc'` is replaced by Karma tests

diff --git a/packages/@lwc/integration-karma/test/synthetic-shadow/element-api/element-api.spec.js b/packages/@lwc/integration-karma/test/synthetic-shadow/element-api/element-api.spec.js
@@ -3,7 +3,7 @@ import { createElement } from 'lwc';
 import Container from 'x/container';
 import ParentSpecialized from 'x/parentSpecialized';
 
-/**
+/*
  <div>
      <x-container>
          <p>ctx first text</p>

diff --git a/packages/@lwc/module-resolver/src/resolve-module.ts b/packages/@lwc/module-resolver/src/resolve-module.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -186,6 +186,25 @@ function resolveModuleRecordType(
     });
 }
 
+/**
+ * Resolves LWC modules using a custom resolution algorithm, using the configuration from your
+ * project's `lwc.config.json` or the `"lwc"` key in the `package.json`. The resolver iterates
+ * through the modules provided in the config and returns the first module that matches the
+ * requested module specifier. There are three types of module record:
+ * - Alias module record: A file path where an LWC module can be resolved.
+ * - Directory module record: A folder path where LWC modules can be resolved.
+ * - NPM package module record: An NPM package that exposes one or more LWC modules.
+ * @param importee The module specifier to resolve
+ * @param dirname The directory to resolve relative to
+ * @param config Root directory and additional modules to
+ * @param config.rootDir Root dir use for module resolution, defaults to `process.cwd()`
+ * @param config.modules Array of additional modules to check, takes precedence over the project config
+ * @returns A registry entry for the resolved module
+ * @throws If the resolver processes an invalid configuration, it throws an error with the
+ * LWC_CONFIG_ERROR error code. If the resolver can't locate the module, it throws an error with the
+ * NO_LWC_MODULE_FOUND error code.
+ * @example resolveModule('x/foo', './index.js')
+ */
 export function resolveModule(
     importee: string,
     dirname: string,

diff --git a/packages/@lwc/module-resolver/src/shared.ts b/packages/@lwc/module-resolver/src/shared.ts
@@ -1,10 +1,16 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 
-export function isObject(obj: any): obj is object {
+/**
+ * Determines whether the given value is an object or null.
+ * @param obj The value to check
+ * @returns true if the value is an object or null
+ * @example isObject(null) // true
+ */
+export function isObject(obj: any): obj is object | null {
     return typeof obj === 'object';
 }
diff --git a/packages/@lwc/rollup-plugin/src/index.ts b/packages/@lwc/rollup-plugin/src/index.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -144,6 +144,11 @@ function transformWarningToRollupLog(
     return result;
 }
 
+/**
+ * Rollup plugin for bundling LWC components
+ * @param pluginOptions LWC rollup plugin options
+ * @returns LWC rollup plugin
+ */
 export default function lwc(pluginOptions: RollupLwcOptions = {}): Plugin {
     const filter = pluginUtils.createFilter(pluginOptions.include, pluginOptions.exclude);
 

diff --git a/packages/@lwc/style-compiler/README.md b/packages/@lwc/style-compiler/README.md
@@ -20,7 +20,7 @@ yarn add --dev @lwc/style-compiler
 ## Usage
 
 ```js
-const compile = require('@lwc/style-compiler');
+const { transform } = require('@lwc/style-compiler');
 
 const source = `
     :host {
@@ -32,12 +32,12 @@ const source = `
     }
 `;
 
-const { code } = compile(source, 'example.css');
+const { code } = transform(source, 'example.css');
 ```
 
 ### API
 
-#### `compile(source, id, options)`
+#### `transform(source, id, options)`
 
 **Options:**
 

diff --git a/packages/@lwc/style-compiler/src/transform.ts b/packages/@lwc/style-compiler/src/transform.ts
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
@@ -10,10 +10,11 @@ import { getAPIVersionFromNumber } from '@lwc/shared';
 import serialize from './serialize';
 import postcssLwc from './postcss-lwc-plugin';
 
+/** Configuration options for CSS transforms. */
 export interface Config {
     /**
-     * @deprecated - Custom property transforms are deprecated because IE11 and other legacy browsers are no longer supported.
      * CSS custom properties configuration
+     * @deprecated Custom property transforms are deprecated because IE11 and other legacy browsers are no longer supported.
      */
     // TODO [#3266]: Remove StylesheetConfig as part of breaking change wishlist
     customProperties?: {
@@ -28,6 +29,23 @@ export interface Config {
     apiVersion?: number;
 }
 
+/**
+ * Transforms CSS for use with LWC components.
+ * @param src Contents of the CSS source file
+ * @param id Filename of the CSS source file
+ * @param config Transformation options
+ * @returns Transformed CSS
+ * @example
+ * const {transform} = require('@lwc/style-compiler');
+ * const source = `
+ *  :host {
+ *    opacity: 0.4;
+ *  }
+ *  span {
+ *    text-transform: uppercase;
+ *  }`;
+ * const { code } = transform(source, 'example.css');
+ */
 export function transform(src: string, id: string, config: Config = {}): { code: string } {
     if (src === '') {
         return { code: 'export default undefined' };

diff --git a/packages/@lwc/synthetic-shadow/src/faux-shadow/portal.ts b/packages/@lwc/synthetic-shadow/src/faux-shadow/portal.ts
@@ -131,7 +131,6 @@ function markElementAsPortal(elm: Element) {
  * child nodes.
  * - at the moment, there is no way to undo this operation, once the element is
  * marked as $domManual$, setting it to false does nothing.
- *
  */
 // TODO [#1306]: rename this to $observerConnection$
 defineProperty(Element.prototype, '$domManual$', {
-Original file line number
+Diff line change
@@ Expand Up @@
         }
     }
-    /*
+    /**
      * Expected API for this plugin:
      * { dynamicImports: { loader: string, strictSpecifier: boolean } }
      */
@@ Expand Down @@