docs: add jsdocs comments for all functions (except computedFrom) (#24

)

* docs: add jsdocs comments for all functions (except `computedFrom`)

closes #18

* docs: added computedFrom jsdocs

---------

Co-authored-by: Enea Jahollari <[email protected]>

libs/ngxtension/assert-injector/src/assert-injector.ts

@@ -1,5 +1,25 @@
 import { Injector, assertInInjectionContext, inject } from '@angular/core';
 
+/**
+ * `assertInjector` extends `assertInInjectionContext` with an optional `Injector`
+ * After assertion, `assertInjector` returns a guaranteed `Injector` whether it is the default `Injector`
+ * within the current **Injection Context** or the custom `Injector` that was passed in.
+ *
+ * @param {Function} fn - the Function to pass in `assertInInjectionContext`
+ * @param {Injector | undefined | null} injector - the optional "custom" Injector
+ * @returns Injector
+ *
+ * @example
+ * ```ts
+ * function injectDestroy(injector?: Injector) {
+ *  injector = assertInjector(injectDestroy, injector);
+ *
+ *  return runInInjectionContext(injector, () => {
+ *    // code
+ *  })
+ * }
+ * ```
+ */
 export function assertInjector(
 	fn: Function,
 	injector: Injector | undefined | null

libs/ngxtension/computed-from/src/computed-from.ts

@@ -33,6 +33,32 @@ export function computedFrom<Input extends object, Output = Input>(
 	injector?: Injector
 ): Signal<Output>;
 
+/**
+ * `computedFrom` is a function that takes an array/object with `Observable` or `Signal` values and returns a `Signal` that
+ * emits the values of the `Observable` or `Signal` values. It is similar to `combineLatest` but it will emit
+ * when the value of the `Observable` or `Signal` changes.
+ *
+ * @param {ObservableSignalInputTuple} sources - array/object of `Observable` or `Signal` values
+ * @param {OperatorFunction} [operator] - operator to apply to the `Observable` or `Signal` values
+ * @param {Injector} [injector] - injector to use to inject the `Observable` or `Signal` values
+ * @returns {Signal} - `Signal` that emits the values of the `Observable` or `Signal` values
+ *
+ * @example
+ *
+ * ```ts
+ * export class MyComponent {
+ *  private readonly filtersService = inject(FiltersService);
+ *  readonly pageNumber = signal(1);
+ *
+ *  readonly data = computedFrom(
+ *   [this.pageNumber, this.filtersService.filters$],
+ *   pipe(
+ *     switchMap(([pageNumber, filters]) => this.dataService.getData(pageNumber, filters)),
+ *     startWith([])
+ *   );
+ * }
+ * ```
+ */
 export function computedFrom(
 	sources: any,
 	operator?: OperatorFunction<any, any>,

libs/ngxtension/create-injection-token/src/create-injection-token.ts

@@ -97,6 +97,23 @@ function createProvideFn<
 	};
 }
 
+/**
+ * `createInjectionToken` accepts a factory function and returns a tuple of `injectFn`, `provideFn`, and the `InjectionToken`
+ * that the factory function is for.
+ *
+ * @param {Function} factory - Factory Function that returns the value for the `InjectionToken`
+ * @param {CreateInjectionTokenOptions} options - object to control how the `InjectionToken` behaves
+ * @returns {CreateInjectionTokenReturn}
+ *
+ * @example
+ * ```ts
+ * const [injectCounter, provideCounter, COUNTER] = createInjectionToken(() => signal(0));
+ *
+ * export class Counter {
+ *  counter = injectCounter(); // WritableSignal<number>
+ * }
+ * ```
+ */
 export function createInjectionToken<
 	TFactory extends (...args: any[]) => any,
 	TFactoryDeps extends Parameters<TFactory> = Parameters<TFactory>,

libs/ngxtension/repeat/src/repeat.ts

@@ -1,6 +1,20 @@
 import { NgFor } from '@angular/common';
 import { Directive, Input } from '@angular/core';
 
+/**
+ * An extension of `NgFor` directive that allows consumers to iterate "x times" instead of through a list of items
+ *
+ * @param {number} count - a positive integer starting from 0
+ *
+ * @example
+ *
+ * ```html
+ * <!-- before -->
+ * <p *ngFor="let i of [0, 1, 2]">{{i}}</p>
+ * <!-- after -->
+ * <p *ngFor="let i; repeat: 3">{{i}}</p>
+ * ```
+ */
 @Directive({
 	standalone: true,
 	selector: '[ngFor][ngForRepeat]',

libs/ngxtension/resize/src/resize.ts

@@ -57,6 +57,18 @@ export type ResizeResult = {
 	readonly dpr: number;
 };
 
+/**
+ * `injectResize` returns an `Observable<ResizeResult>` that observes the `resize` event on the Host element
+ * of the component. `options` passed in is merged with default options
+ *
+ * @see {@link defaultResizeOptions}
+ *
+ * @param {Partial<ResizeOptions>} [options={}]
+ * @see {@link ResizeOptions}
+ *
+ * @returns {Observable<ResizeResult>}
+ * @see {@link ResizeResult}
+ */
 export function injectResize(
 	options: Partial<ResizeOptions> = {}
 ): Observable<ResizeResult> {
@@ -69,6 +81,16 @@ export function injectResize(
 	return createResizeStream(mergedOptions, nativeElement, document, zone);
 }
 
+/**
+ * A directive to be used on any element instead of the Host element. For Host element, there are 3 approaches:
+ * - use {@link injectResize}
+ * - use `hostDirectives`  with `HostListener` on `ngxResize`
+ *
+ * @param {Partial<ResizeOptions>} - partial options to control `Resize` behavior. merged with default options
+ * @see {@link defaultResizeOptions}
+ *
+ * @returns {ResizeResult} - as an Output `(ngxResize)`
+ */
 @Directive({ selector: '[ngxResize]', standalone: true })
 export class NgxResize implements OnInit {
 	@Input() ngxResizeOptions: Partial<ResizeOptions> = {};