docs: add API reference docs

projects/ngx-meta/api-extractor/ngx-meta.api.md

@@ -419,7 +419,7 @@ export const provideNgxMetaJsonLd: () => Provider[];
 
 // Warning: (ae-incompatible-release-tags) The symbol "provideNgxMetaManager" is marked as @alpha, but its signature references "_ProvideNgxMetaManagerOptions" which is marked as @internal
 //
-// @alpha (undocumented)
+// @alpha
 export const provideNgxMetaManager: <T>(jsonPath: string, setterFactory: MetadataSetterFactory<T>, options?: _ProvideNgxMetaManagerOptions) => FactoryProvider;
 
 // @internal (undocumented)
@@ -604,25 +604,20 @@ export const withContentAttribute: {
 
 // Warning: (ae-incompatible-release-tags) The symbol "withManagerDeps" is marked as @alpha, but its signature references "_ProvideNgxMetaManagerOptions" which is marked as @internal
 //
-// @alpha (undocumented)
+// @alpha
 export const withManagerDeps: (...deps: Exclude<FactoryProvider['deps'], undefined>) => _ProvideNgxMetaManagerOptions;
 
 // Warning: (ae-incompatible-release-tags) The symbol "withManagerGlobal" is marked as @alpha, but its signature references "_ProvideNgxMetaManagerOptions" which is marked as @internal
 //
-// @alpha (undocumented)
+// @alpha
 export const withManagerGlobal: (global: string) => _ProvideNgxMetaManagerOptions;
 
-// Warning: (ae-incompatible-release-tags) The symbol "withManagerId" is marked as @alpha, but its signature references "_ProvideNgxMetaManagerOptions" which is marked as @internal
-//
-// @alpha (undocumented)
-export const withManagerId: (id: string) => _ProvideNgxMetaManagerOptions;
-
-// @alpha (undocumented)
+// @alpha
 export const withManagerJsonPath: (...jsonPath: MetadataResolverOptions['jsonPath']) => string;
 
 // Warning: (ae-incompatible-release-tags) The symbol "withManagerObjectMerging" is marked as @alpha, but its signature references "_ProvideNgxMetaManagerOptions" which is marked as @internal
 //
-// @alpha (undocumented)
+// @alpha
 export const withManagerObjectMerging: () => _ProvideNgxMetaManagerOptions;
 
 // @public
@@ -634,7 +629,7 @@ export const withNgxMetaBaseUrl: (baseUrl: BaseUrl) => CoreFeature<CoreFeatureKi
 // @public
 export const withNgxMetaDefaults: (defaults: MetadataValues) => CoreFeature<CoreFeatureKind.Defaults>;
 
-// @alpha (undocumented)
+// @alpha
 export const withOptions: <T extends object>(...options: ReadonlyArray<T>) => T;
 
 // @public

projects/ngx-meta/src/core/src/managers/ngx-meta-metadata-manager.ts

@@ -10,10 +10,12 @@ import { inject } from '@angular/core'
  *
  * See also:
  *
- * - {@link https://ngx-meta.dev/guides/manage-your-custom-metadata/ | Manage your custom metadata}
+ * - {@link https://ngx-meta.dev/guides/manage-your-custom-metadata/ | Manage your custom metadata guide}
  *
  * - {@link makeMetadataManagerProviderFromSetterFactory} for a helper to create a metadata manager
  *
+ * - {@link provideNgxMetaManager} for an experimental helper to create a metadata manager
+ *
  * @typeParam Value - Value type that can be handled by the setter
  *
  * @public

projects/ngx-meta/src/core/src/managers/provider/index.ts

@@ -2,7 +2,6 @@ export {
   provideNgxMetaManager,
   withManagerDeps,
   withManagerGlobal,
-  withManagerId,
   withManagerObjectMerging,
   withManagerJsonPath,
   _ProvideNgxMetaManagerOptions,

projects/ngx-meta/src/core/src/managers/provider/provide-ngx-meta-manager.spec.ts

@@ -9,7 +9,6 @@ import {
   provideNgxMetaManager,
   withManagerDeps,
   withManagerGlobal,
-  withManagerId,
   withManagerObjectMerging,
 } from './provide-ngx-meta-manager'
 
@@ -71,18 +70,6 @@ describe('provide manager', () => {
     })
   })
 
-  describe('when an id is given', () => {
-    const id = 'id'
-
-    it('should set it in the manager', () => {
-      const provider = makeSut({ id })
-
-      const manager = provideAndInject(provider)
-
-      expect(manager.id).toEqual(id)
-    })
-  })
-
   describe('when object merging is enabled', () => {
     const objectMerge = true
 
@@ -102,7 +89,6 @@ const makeSut = (
     factory?: MetadataSetterFactory<unknown>
     deps?: FactoryProvider['deps']
     global?: string
-    id?: string
     objectMerge?: true
   } = {},
 ) =>
@@ -113,7 +99,6 @@ const makeSut = (
       ...[
         opts.deps ? withManagerDeps(...opts.deps) : undefined,
         opts.global ? withManagerGlobal(opts.global) : undefined,
-        opts.id ? withManagerId(opts.id) : undefined,
         opts.objectMerge ? withManagerObjectMerging() : undefined,
       ].filter(_isDefined),
     ),

projects/ngx-meta/src/core/src/managers/provider/provide-ngx-meta-manager.ts

@@ -6,10 +6,55 @@ import {
 } from '../ngx-meta-metadata-manager'
 
 /**
- * @param jsonPath -
- * @param setterFactory -
- * @param options -
+ * Creates an {@link NgxMetaMetadataManager} provider to manage some metadata.
  *
+ * Check out {@link https://ngx-meta.dev/guides/manage-your-custom-metadata/ | manage your custom metadata guide} to
+ * learn how to provide your custom metadata managers.
+ *
+ * @remarks
+ *
+ * Options can be specified using helper functions. {@link withOptions} can be used to combine more than one.
+ *
+ * Available option functions:
+ *
+ *  - {@link withManagerDeps}
+ *
+ *  - {@link withManagerGlobal}
+ *
+ *  - {@link withManagerObjectMerging}
+ *
+ * @example
+ *
+ * ```typescript
+ * const CUSTOM_TITLE_PROVIDER = provideNgxMetaManager<string | undefined>(
+ *     'custom.title',
+ *     (metaElementsService: NgxMetaElementsService) => (value) => {
+ *       metaElementsService.set(
+ *         withNameAttribute('custom:title'),
+ *         withContentAttribute(value),
+ *       )
+ *     },
+ *     withOptions(
+ *      withManagerDeps(NgxMetaElementsService),
+ *      withGlobal('title'),
+ *     ),
+ *   )
+ * ```
+ *
+ * @param jsonPath - Path to access the metadata value this manager needs given a JSON object
+ *                   containing metadata values. Path is expressed as the keys to use to access the value
+ *                   joined by a "." character.
+ *                   You can use {@link withManagerJsonPath} to provide an array of keys instead.
+ *                   For more information, checkout {@link MetadataResolverOptions.jsonPath}
+ * @param setterFactory - Factory function that creates the {@link MetadataSetter} function for the manager (which
+ *                        manages the metadata element on the page).
+ *                        You can inject dependencies either using {@link withManagerDeps} option, that will be passed
+ *                        as arguments to the setter factory function. This way is preferred, as takes fewer bytes of
+ *                        your bundle size. However, type safety depends on you.
+ *                        Or use {@link https://angular.dev/api/core/inject | Angular's `inject` function} for a more
+ *                        type-safe option.
+ * @param options - Extra options for the metadata manager provider creation. Use one of the helpers listed in this
+ *                  method's reference docs to supply one or more of them.
  * @alpha
  */
 export const provideNgxMetaManager = <T>(
@@ -22,7 +67,7 @@ export const provideNgxMetaManager = <T>(
   multi: true,
   useFactory: (...deps: ReadonlyArray<unknown>) =>
     ({
-      id: options.i ?? jsonPath,
+      id: jsonPath,
       set: setterFactory(...deps),
       resolverOptions: {
         jsonPath: jsonPath.split('.'),
@@ -44,8 +89,15 @@ export type _ProvideNgxMetaManagerOptions = Partial<{
 }>
 
 /**
+ * Specifies dependencies to inject to the setter factory function passed to {@link provideNgxMetaManager}
  *
- * @param deps -
+ * See also:
+ *
+ * - {@link https://angular.dev/guide/di/dependency-injection-providers#factory-providers-usefactory:~:text=property%20is%20an%20array%20of%20provider%20tokens | Factory providers' deps}
+ *
+ * - {@link https://angular.dev/api/core/FactoryProvider#deps | FactoryProvider#deps}
+ *
+ * @param deps - Dependencies to inject. Each argument declares the dependency to inject.
  *
  * @alpha
  */
@@ -56,8 +108,9 @@ export const withManagerDeps = (
 })
 
 /**
+ * Sets the global key to use for a metadata manager created with {@link provideNgxMetaManager}
  *
- * @param global -
+ * @param global - See {@link MetadataResolverOptions.global}
  *
  * @alpha
  */
@@ -66,25 +119,22 @@ export const withManagerGlobal = (
 ): _ProvideNgxMetaManagerOptions => ({ g: global })
 
 /**
+ * Enables object merging for the manager being created with {@link provideNgxMetaManager}
  *
- * @param id -
+ * See {@link MetadataResolverOptions.objectMerge} for more information.
  *
  * @alpha
  */
-export const withManagerId = (id: string): _ProvideNgxMetaManagerOptions => ({
-  i: id,
-})
-
-/**
- * @alpha
- */
 export const withManagerObjectMerging = (): _ProvideNgxMetaManagerOptions => ({
   o: true,
 })
 
 /**
+ * Transforms a JSON Path specified as an array of keys into a string joined by dots.
+ *
+ * Useful to use with {@link provideNgxMetaManager} to avoid repeating same keys around.
  *
- * @param jsonPath -
+ * @param jsonPath - Parts of the JSON Path to join into a string.
  *
  * @alpha
  */

projects/ngx-meta/src/core/src/utils/with-options.ts

@@ -1,6 +1,14 @@
 /**
+ * Helper function to combine multiple options (objects).
  *
- * @param options -
+ * In case of specifying same options more than once, the latter one will take precedence.
+ * Provide them sorted by ascendant priority. Less priority options first. Top priority options last.
+ *
+ * Can be used to combine options for:
+ *
+ * - {@link provideNgxMetaManager}
+ *
+ * @param options - Options to combine.
  *
  * @alpha
  */