docs: fix references with @link and validate via CI

.github/workflows/run-tests.yaml

@@ -152,3 +152,31 @@ jobs:
 
       - name: Run type-checking
         run: npm run tsc:ci
+
+  typedoc:
+    name: Typedoc validation
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 24.15.0
+          registry-url: https://registry.npmjs.org/
+
+      - name: Restore node_modules
+        id: node-modules-cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: node_modules
+          key: node-modules-${{ runner.os }}-node24.15.0-${{ hashFiles('package-lock.json', 'patches/**') }}
+
+      - name: Install NPM dependencies (cache miss fallback)
+        if: steps.node-modules-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit --no-fund
+
+      - name: Run typedoc validation
+        run: npm run docs:ci:validate

.husky/defaults.json

@@ -4,6 +4,7 @@
 	"lintOnCommit": false,
 	"lintCssOnCommit": false,
 	"typecheckOnCommit": false,
+	"typedocOnCommit": false,
 	"testOnCommit": false,
 
 	"skipCommitMsg": false,

.husky/pre-commit

@@ -73,3 +73,16 @@ then
 		exit 1
 	fi
 fi
+
+if [ "$POLAR_TYPEDOC_ON_COMMIT" = "yes" ]
+then
+	if ! npm run docs:ci:validate
+	then
+		echo "Cannot commit: Typedoc validation failed." >&2
+		echo "Please fix the above error(s)." >&2
+		echo >&2
+		echo "If you want to commit anyway, set POLAR_TYPEDOC_ON_COMMIT=no" >&2
+		echo "If you want to skip all pre-commit checks, set POLAR_SKIP_PRE_COMMIT=yes" >&2
+		exit 1
+	fi
+fi

eslint.config.ts

@@ -96,6 +96,7 @@ const polarTsConfig = defineConfig({
 				allowNumber: true,
 			},
 		],
+		'tsdoc/syntax': 'off',
 
 		// POLAR-specific rules
 		'perfectionist/sort-interfaces': [

package.json

@@ -59,6 +59,7 @@
 		"tsc": "tsc && vue-tsc -p src && vue-tsc -p examples/iceberg",
 		"tsc:ci": "tsc && vue-tsc -p src && vue-tsc -p examples/iceberg",
 		"docs:ci": "npm run docs:showcase:ci && npm run docs:docs:ci && npm run docs:api:ci && npm run docs:api:core:ci && npm run docs:api:plugin:ci",
+		"docs:ci:validate": "typedoc --targetAudience core",
 		"docs:showcase:ci": "npm run build:github-io && mkdir -p docs-html && cp -r examples/github-io/dist/* docs-html/",
 		"docs:docs": "mkdocs serve",
 		"docs:docs:ci": "mkdocs build",

src/composables/useStoreWatcher.ts

@@ -1,8 +1,6 @@
-/* eslint-disable tsdoc/syntax */
 /**
  * @module \@polar/polar/composables/useStoreWatcher
  */
-/* eslint-enable tsdoc/syntax */
 
 import type { ComputedRef, WatchOptions, WatchStopHandle } from 'vue'
 import type { StoreReference } from '@/core/types'

src/core/index.ts

@@ -1,4 +1,3 @@
-/* eslint-disable tsdoc/syntax */
 /**
  * This is the main export for the NPM package \@polar/polar.
  *
@@ -7,7 +6,6 @@
  * @packageDocumentation
  * @module \@polar/polar
  */
-/* eslint-enable tsdoc/syntax */
 
 import { defineCustomElement } from 'vue'
 

src/core/locales.ts

@@ -1,11 +1,9 @@
-/* eslint-disable tsdoc/syntax */
 /**
  * This is the documentation for the locales keys in POLAR core.
  * These locales are *NOT* exported, but documented only.
  *
  * @module locales/core
  */
-/* eslint-enable tsdoc/syntax */
 
 import type { Locale } from './types'
 

src/core/stores/index.ts

@@ -1,8 +1,6 @@
-/* eslint-disable tsdoc/syntax */
 /**
  * @module \@polar/polar/store
  */
-/* eslint-enable tsdoc/syntax */
 
 import { acceptHMRUpdate, defineStore, storeToRefs } from 'pinia'
 import { computed } from 'vue'
@@ -12,13 +10,11 @@ import { useMarkerStore } from './marker'
 import { useMoveHandleStore } from './moveHandle'
 import { usePluginStore } from './plugin'
 
-/* eslint-disable tsdoc/syntax */
 /**
  * @function
  *
  * Core store of POLAR.
  */
-/* eslint-enable tsdoc/syntax */
 export const useCoreStore = defineStore('core', () => {
 	const mainStore = useMainStore()
 	const mainStoreRefs = storeToRefs(mainStore)
@@ -75,8 +71,7 @@ export const useCoreStore = defineStore('core', () => {
 		deviceIsHorizontal: computed(() => mainStore.deviceIsHorizontal),
 
 		/**
-		 * Whether the map has a maximum height of {@link SMALL_DISPLAY_HEIGHT} and
-		 * a maximum width of {@link SMALL_DISPLAY_WIDTH}.
+		 * Whether the map has a small display.
 		 *
 		 * @alpha
 		 * @readonly
@@ -165,7 +160,7 @@ export const useCoreStore = defineStore('core', () => {
 		 *
 		 * If no plugin with the specified ID is loaded, `null` is returned instead.
 		 *
-		 * @param pluginId - ID of the plugin whose store is requested.
+		 * @param id - ID of the plugin whose store is requested.
 		 */
 		getPluginStore: pluginStore.getPluginStore,
 
@@ -245,7 +240,7 @@ export const useCoreStore = defineStore('core', () => {
 
 		/**
 		 * Returns the effective layer configuration or `null` if the layer was not found.
-		 * The configuration is merged from the {@link createMap | serviceRegister parameter of createMap} and the POLAR {@link MapConfiguration.layers | layers} configuration.
+		 * The configuration is merged from the {@link @polar/polar!createMap | serviceRegister parameter of createMap} and the POLAR {@link @polar/polar!MapConfiguration.layers | layers} configuration.
 		 *
 		 * @param layerId - Layer ID
 		 * @returns Layer configuration (object) or `null`

src/core/types/layer.ts

@@ -119,9 +119,9 @@ export interface LayerConfiguration {
 	options?: LayerConfigurationOptions
 
 	/**
-	 * ID of the used style. If the layer is also configured in {@link MapConfiguration.markers | `mapConfiguration.markers`},
+	 * ID of the used style. If the layer is also configured in {@link @polar/polar!MapConfiguration.markers | `mapConfiguration.markers`},
 	 * that configuration takes precedence over the configured `styleId`. Only applicable for vector-type layers.
-	 * For more information and an example see {@link MapConfiguration.featureStyles | `mapConfiguration.featureStyles`}.
+	 * For more information and an example see {@link @polar/polar!MapConfiguration.featureStyles | `mapConfiguration.featureStyles`}.
 	 * Defaults and fallbacks to OpenLayers default styling.
 	 */
 	styleId?: string

src/core/types/main.ts

@@ -184,7 +184,7 @@
 export interface MapConfiguration extends MasterportalApiConfiguration {
 	/**
 	 * Configuration of layers that are supposed to be used in the respective client. All layers defined here have to have
-	 * an entry in the {@link createMap | `serviceRegister` parameter of `createMap`}. If `@polar/plugin-layer-chooser` is
+	 * an entry in the {@link @polar/polar!createMap | `serviceRegister` parameter of `createMap`}. If `@polar/plugin-layer-chooser` is
 	 * installed and configured, all these layers will be displayed in that menu.
 	 *
 	 * @example
@@ -304,7 +304,7 @@
 
 	// Plugins are not sorted alphabetical, but listed last.
 	// Remember to sort them alphabetical inside their space.
 	// TODO: Generate this section via types/plugin.ts
 	/* eslint-disable perfectionist/sort-interfaces */
 
 	/** Configuration for addressSearch plugin. */

src/core/types/marker.ts

@@ -74,7 +74,7 @@ export interface MarkerLayer {
 }
 
 export interface MarkerLayerConfiguration {
-	/** Unique identifier of a layer configured in {@link MapConfiguration.layers | `mapConfiguration.layers`}. */
+	/** Unique identifier of a layer configured in {@link @polar/polar!MapConfiguration.layers | `mapConfiguration.layers`}. */
 	id: string
 
 	/**

src/core/types/plugin.ts

@@ -55,32 +55,32 @@
  *
  * ## Custom Plugin Positioning
  *
- * There are two implemented layouting systems in POLAR configured by {@link MapConfiguration.layout}.
+ * There are two implemented layouting systems in POLAR configured by {@link @polar/polar!MapConfiguration.layout}.
  *
  * If `layout` is set to `'nineRegions'` all plugins are placed in a predefined region grid.
  * Use {@link PluginOptions.displayComponent | displayComponent} to control visibility
  * and {@link PluginOptions.layoutTag | layoutTag} to specify the target region.
  *
  * If `layout` is set to `'standard'`, a plugin can be rendered in one of two ways:
  * 1. **As part of the IconMenu**: Configure the plugin in the IconMenu's
- * 		{@link IconMenuPluginOptions.menus | `menus`} configuration.
+ * 		{@link @polar/polar/plugins/iconMenu!IconMenuPluginOptions.menus | `menus`} configuration.
  * 		The IconMenu will handle positioning and rendering the plugin at the designated location.
  * 2. **Independent with CSS positioning**: Directly add the plugin with
- * 		{@link addPlugin}. The plugin is responsible for its own positioning
+ * 		{@link @polar/polar!addPlugin | addPlugin}. The plugin is responsible for its own positioning
  * 		using CSS (e.g., `position: absolute`) within the map container.
  */
 export interface PluginOptions {
 	/**
 	 * Should the component be visible at all.
-	 * Only relevant if {@link MapConfiguration.layout | layout} is set to `'nineRegions'`.
+	 * Only relevant if {@link @polar/polar!MapConfiguration.layout | layout} is set to `'nineRegions'`.
 	 *
 	 * @defaultValue `false`
 	 */
 	displayComponent?: boolean
 
 	/**
 	 * The region where the plugin should be rendered.
-	 * Required if {@link MapConfiguration.layout | layout} is set to `'nineRegions'`,
+	 * Required if {@link @polar/polar!MapConfiguration.layout | layout} is set to `'nineRegions'`,
 	 * ignored otherwise.
 	 */
 	layoutTag?: keyof typeof NineLayoutTag
@@ -152,7 +152,7 @@
 type GetPluginStore<
 	T extends BundledPluginId,
 	I extends BundledPluginId,
 	// TODO: This fixes the type error, but relaxes type-checking for the plugin store too much.
 	// However, it is not clear if Pinia's type system allows for stronger checks at the moment.
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	S extends PolarPluginStore<any>,
@@ -284,7 +284,7 @@
 
 	/**
 	 * Configuration options. Please also note that all configuration added via plugin constructors can be overridden in
-	 * the {@link createMap | `createMap`'s parameter `mapConfiguration`} .
+	 * the {@link @polar/polar!createMap | `createMap`'s parameter `mapConfiguration`} .
 	 *
 	 * You may use either object (or a mix of them) to create the configuration, e.g. use the constructors for a base
 	 * configuration and the `mapConfiguration` object to override it for various use cases.

src/core/utils/export/store.ts

@@ -67,7 +67,7 @@ export function subscribe<T extends StoreId>(
 }
 
 /**
- * Updates the parameter {@link parameterName | parameter} in the {@link storeName | store} with the {@link payload}.
+ * Updates the parameter `parameterName` in the `storeName` store with the `payload`.
  *
  * @param map - Map to update the value at.
  * @param storeName - Either `'core'` for the core store or the plugin ID for a plugin's store.

src/plugins/addressSearch/index.ts

@@ -1,8 +1,6 @@
-/* eslint-disable tsdoc/syntax */
 /**
  * @module \@polar/polar/plugins/addressSearch
  */
-/* eslint-enable tsdoc/syntax */
 
 import type { PluginContainer, PolarPluginStore } from '@/core'
 import type { AddressSearchPluginOptions } from './types'
@@ -24,7 +22,7 @@ import { PluginId } from './types'
  * - WFS
  * - Hamburg WFS-G (`mpapi`), may fit some WFS-G outside HH, testing is advised
  *
- * @returns Plugin for use with {@link addPlugin}.
+ * @returns Plugin for use with {@link @polar/polar!addPlugin | addPlugin}
  */
 export default function pluginAddressSearch(
 	options: AddressSearchPluginOptions

src/plugins/addressSearch/locales.ts

@@ -1,11 +1,9 @@
-/* eslint-disable tsdoc/syntax */
 /**
  * This is the documentation for the locales keys in the addressSearch plugin.
  * These locales are *NOT* exported, but documented only.
  *
  * @module locales/plugins/addressSearch
  */
-/* eslint-enable tsdoc/syntax */
 
 import type { Locale } from '@/core'
 

src/plugins/addressSearch/store.ts

@@ -1,8 +1,6 @@
-/* eslint-disable tsdoc/syntax */
 /**
  * @module \@polar/polar/plugins/addressSearch/store
  */
-/* eslint-enable tsdoc/syntax */
 
 import type { PolarGeoJsonFeature } from '@/core'
 import type {
@@ -24,13 +22,11 @@
 import { getMethodContainer } from './utils/methodContainer'
 import SearchResultSymbols from './utils/searchResultSymbols'
 
-/* eslint-disable tsdoc/syntax */
 /**
  * @function
  *
  * Plugin store for the address search.
  */
-/* eslint-enable tsdoc/syntax */
 export const useAddressSearchStore = defineStore(
 	'plugins/addressSearch',
 	() => {
@@ -181,7 +177,7 @@
 			methodContainer = getMethodContainer()
 			selectedGroupId.value = groupIds.value[0] as string
 			if (configuration.value.customSearchMethods) {
 				// TODO: The method was bound to the store before, test with DISH if still required
 				methodContainer.registerSearchMethods(
 					configuration.value.customSearchMethods
 				)
@@ -348,7 +344,7 @@
 			/**
 			 * ID of the currently selected group.
 			 * Changing this triggers a new search with the currently set value
-			 * for {@link inputValue} if it has at least one character.
+			 * for `inputValue` if it has at least one character.
 			 */
 			selectedGroupId,
 

src/plugins/addressSearch/types.ts

@@ -54,7 +54,7 @@ export interface GroupProperties {
  *
  * @remarks
  * In {@link categoryProperties} and {@link groupProperties}, id strings called
- * {@link groupId} and {@link categoryId} are used. These are arbitrary strings
+ * `groupId` and `categoryId` are used. These are arbitrary strings
  * you can introduce and reuse to group or categorize elements together.
  */
 export interface AddressSearchPluginOptions extends PluginOptions {
@@ -74,9 +74,9 @@ export interface AddressSearchPluginOptions extends PluginOptions {
 
 	/**
 	 * An object defining properties for a category.
-	 * The searchMethod's {@link AddressSearchPluginOptions.categoryId | addressSearch.categoryId} is used as identifier.
+	 * The searchMethod's {@link SearchMethodConfiguration.categoryId | categoryId} is used as identifier.
 	 *
-	 * A service without categoryId default to the {@link AddressSearchPluginOptions.categoryId | addressSearch.categoryId}
+	 * A service without categoryId defaults to the {@link SearchMethodConfiguration.categoryId | categoryId}
 	 * `"default"`.
 	 */
 	categoryProperties?: Record<string, CategoryProperties>
@@ -130,6 +130,12 @@ export type SearchType = 'bkg' | 'wfs' | 'mpapi' | string
 
 export type SearchDisplayMode = 'mixed' | 'categorized'
 
+export type {
+	BKGParameters,
+	MpapiParameters,
+	WfsParameters,
+} from '../../lib/getFeatures/types'
+
 /** Object containing information for a specific search method. */
 export interface SearchMethodConfiguration {
 	/**
@@ -176,7 +182,7 @@ export interface SearchMethodConfiguration {
 
 	/**
 	 * The object further describes details for the search request.
-	 * Its contents vary by service type, see {@link BKGParameters}, {@link MpapiParameters} or {@link WfsParameters}.
+	 * Its contents vary by service type, see {@link @polar/polar/plugins/addressSearch!BKGParameters}, {@link @polar/polar/plugins/addressSearch!MpapiParameters} or {@link @polar/polar/plugins/addressSearch!WfsParameters}.
 	 */
 	queryParameters?: QueryParameters
 

src/plugins/attributions/index.ts

@@ -1,8 +1,6 @@
-/* eslint-disable tsdoc/syntax */
 /**
  * @module \@polar/polar/plugins/attributions
  */
-/* eslint-enable tsdoc/syntax */
 
 import type { PluginContainer, PolarPluginStore } from '@/core'
 import type { AttributionsPluginOptions } from './types'
@@ -16,7 +14,7 @@ import { PluginId } from './types'
  * Creates a plugin which adds attributions (copyright information) regarding all currently active layers.
  * Additionally, static information can be added.
  *
- * @returns Plugin for use with {@link addPlugin}.
+ * @returns Plugin for use with {@link @polar/polar!addPlugin | addPlugin}
  */
 export default function pluginAttributions(
 	options: AttributionsPluginOptions

src/plugins/attributions/locales.ts

@@ -1,13 +1,11 @@
 import type { Locale } from '@/core'
 
-/* eslint-disable tsdoc/syntax */
 /**
  * This is the documentation for the locales keys in the attributions plugin.
  * These locales are *NOT* exported, but documented only.
  *
  * @module locales/plugins/attributions
  */
-/* eslint-enable tsdoc/syntax */
 
 /**
  * German locales for attributions plugin.