Merge pull request #2174 from umbraco/v14/chore/eslint-jsdocs

Chore: Lint JsDocs

Author: madsrasmussen

eslint.config.js

@@ -6,13 +6,15 @@ import wcPlugin from 'eslint-plugin-wc';
 import litPlugin from 'eslint-plugin-lit';
 import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
 import tseslint from 'typescript-eslint';
+import jsdoc from 'eslint-plugin-jsdoc';
 
 export default [
 	// Recommended config applied to all files
 	js.configs.recommended,
 	...tseslint.configs.recommended,
 	wcPlugin.configs['flat/recommended'],
 	litPlugin.configs['flat/recommended'],
+	jsdoc.configs['flat/recommended'], // We use the non typescript version to allow types to be defined in the jsdoc comments. This will allow js docs as an alternative to typescript types.
 	localRules.configs.all,
 	eslintPluginPrettierRecommended,
 
@@ -46,7 +48,7 @@ export default [
 		},
 		rules: {
 			semi: ['warn', 'always'],
-			"prettier/prettier": ["warn", { "endOfLine": "auto" }],
+			'prettier/prettier': ['warn', { endOfLine: 'auto' }],
 			'no-unused-vars': 'off', //Let '@typescript-eslint/no-unused-vars' catch the errors to allow unused function parameters (ex: in interfaces)
 			'no-var': 'error',
 			...importPlugin.configs.recommended.rules,

package-lock.json

@@ -247,6 +247,7 @@
 		"eslint": "^9.7.0",
 		"eslint-config-prettier": "^9.1.0",
 		"eslint-plugin-import": "^2.29.1",
+		"eslint-plugin-jsdoc": "^48.11.0",
 		"eslint-plugin-lit": "^1.14.0",
 		"eslint-plugin-local-rules": "^3.0.2",
 		"eslint-plugin-prettier": "^5.1.3",

package.json

@@ -60,6 +60,7 @@ export class UmbAppAuthController extends UmbControllerBase {
 	/**
 	 * Starts the authorization flow.
 	 * It will check which providers are available and either redirect directly to the provider or show a provider selection screen.
+	 * @param userLoginState
 	 */
 	async makeAuthorizationRequest(userLoginState: UmbUserLoginState = 'loggingIn'): Promise<boolean> {
 		if (!this.#authContext) {

src/apps/app/app-auth.controller.ts

@@ -10,31 +10,27 @@ import { UmbTextStyles } from '@umbraco-cms/backoffice/style';
 export class UmbAppErrorElement extends UmbLitElement {
 	/**
 	 * The headline to display
-	 *
 	 * @attr
 	 */
 	@property()
 	errorHeadline?: string | null;
 
 	/**
 	 * The error message to display
-	 *
 	 * @attr
 	 */
 	@property()
 	errorMessage?: string | null;
 
 	/**
 	 * The error to display
-	 *
 	 * @attr
 	 */
 	@property()
 	error?: unknown;
 
 	/**
 	 * Hide the back button
-	 *
 	 * @attr
 	 */
 	@property({ type: Boolean, attribute: 'hide-back-button' })

src/apps/app/app-error.element.ts

@@ -25,7 +25,6 @@ import { hasOwnOpener, retrieveStoredPath } from '@umbraco-cms/backoffice/utils'
 export class UmbAppElement extends UmbLitElement {
 	/**
 	 * The base URL of the configured Umbraco server.
-	 *
 	 * @attr
 	 * @remarks This is the base URL of the Umbraco server, not the base URL of the backoffice.
 	 */
@@ -39,7 +38,6 @@ export class UmbAppElement extends UmbLitElement {
 
 	/**
 	 * The base path of the backoffice.
-	 *
 	 * @attr
 	 */
 	@property({ type: String })

src/apps/app/app.element.ts

@@ -24,7 +24,7 @@ export class UmbServerConnection {
 
 	/**
 	 * Gets the URL of the server.
-	 * @return {*}
+	 * @returns {*}
 	 * @memberof UmbServerConnection
 	 */
 	getUrl() {
@@ -33,7 +33,7 @@ export class UmbServerConnection {
 
 	/**
 	 * Gets the status of the server.
-	 * @return {string}
+	 * @returns {string}
 	 * @memberof UmbServerConnection
 	 */
 	getStatus() {
@@ -43,7 +43,7 @@ export class UmbServerConnection {
 
 	/**
 	 * Checks if the server is connected.
-	 * @return {boolean}
+	 * @returns {boolean}
 	 * @memberof UmbServerConnection
 	 */
 	getIsConnected() {

src/apps/app/server-connection.ts

@@ -38,7 +38,7 @@ export class UmbInstallerContext {
 	/**
 	 * Observable method to get the current step in the installation process
 	 * @public
-	 * @return {*}  {Observable<number>}
+	 * @returns {*}  {Observable<number>}
 	 * @memberof UmbInstallerContext
 	 */
 	public currentStepChanges(): Observable<number> {
@@ -48,7 +48,7 @@ export class UmbInstallerContext {
 	/**
 	 * Observable method to get the install status in the installation process
 	 * @public
-	 * @return {*}  {(Observable<ProblemDetails | null>)}
+	 * @returns {*}  {(Observable<ProblemDetails | null>)}
 	 * @memberof UmbInstallerContext
 	 */
 	public installStatusChanges(): Observable<ProblemDetails | null> {
@@ -96,7 +96,7 @@ export class UmbInstallerContext {
 	/**
 	 * Get the data for the installation process
 	 * @public
-	 * @return {*}  {PostInstallRequest}
+	 * @returns {*}  {PostInstallRequest}
 	 * @memberof UmbInstallerContext
 	 */
 	public getData(): InstallRequestModel {

src/apps/installer/installer.context.ts

@@ -13,7 +13,7 @@ export interface UmbClassInterface extends UmbControllerHost {
 	 * @description Observe an Observable. An Observable is a declared source of data that can be observed. An observables is declared from a UmbState.
 	 * @param {Observable<T>} source An Observable to observe from.
 	 * @param {method} callback Callback method called when data is changed.
-	 * @return {UmbObserverController} Reference to the created Observer Controller instance.
+	 * @returns {UmbObserverController} Reference to the created Observer Controller instance.
 	 * @memberof UmbClassMixin
 	 */
 	observe<
@@ -38,7 +38,7 @@ export interface UmbClassInterface extends UmbControllerHost {
 	 * @description Provide a context API for this or child elements.
 	 * @param {string} contextAlias
 	 * @param {instance} instance The API instance to be exposed.
-	 * @return {UmbContextProviderController} Reference to the created Context Provider Controller instance
+	 * @returns {UmbContextProviderController} Reference to the created Context Provider Controller instance
 	 * @memberof UmbClassMixin
 	 */
 	provideContext<R = unknown>(alias: string | UmbContextToken<R>, instance: R): UmbContextProviderController<R>;
@@ -47,7 +47,7 @@ export interface UmbClassInterface extends UmbControllerHost {
 	 * @description Setup a subscription for a context. The callback is called when the context is resolved.
 	 * @param {string} contextAlias
 	 * @param {method} callback Callback method called when context is resolved.
-	 * @return {UmbContextConsumerController} Reference to the created Context Consumer Controller instance
+	 * @returns {UmbContextConsumerController} Reference to the created Context Consumer Controller instance
 	 * @memberof UmbClassMixin
 	 */
 	consumeContext<BaseType = unknown, ResultType extends BaseType = BaseType>(
@@ -58,7 +58,7 @@ export interface UmbClassInterface extends UmbControllerHost {
 	/**
 	 * @description Retrieve a context. Notice this is a one time retrieving of a context, meaning if you expect this to be up to date with reality you should instead use the consumeContext method.
 	 * @param {string} contextAlias
-	 * @return {Promise<ContextType>} A Promise with the reference to the Context Api Instance
+	 * @returns {Promise<ContextType>} A Promise with the reference to the Context Api Instance
 	 * @memberof UmbClassMixin
 	 */
 	getContext<BaseType = unknown, ResultType extends BaseType = BaseType>(

src/libs/class-api/class.interface.ts

@@ -18,7 +18,7 @@ export interface UmbContextRequestEvent<ResultType = unknown> extends Event {
 /**
  * @export
  * @class UmbContextRequestEventImplementation
- * @extends {Event}
+ * @augments {Event}
  * @implements {UmbContextRequestEvent}
  */
 export class UmbContextRequestEventImplementation<ResultType = unknown>