DS-4107 Improve TypeDocs

src/app/core/browse/browse.service.ts

@@ -34,6 +34,9 @@ import { URLCombiner } from '../url-combiner/url-combiner';
 import { Item } from '../shared/item.model';
 import { DSpaceObject } from '../shared/dspace-object.model';
 
+/**
+ * Service that performs all actions that have to do with browse.
+ */
 @Injectable()
 export class BrowseService {
   protected linkPath = 'browses';

src/app/core/shared/dspace-object.model.ts

@@ -54,27 +54,57 @@ export class DSpaceObject implements CacheableObject, ListableObject {
    */
   owner: Observable<RemoteData<DSpaceObject>>;
 
-  /** Gets all matching metadata in this DSpaceObject. See `Metadata.all` for more information. */
+  /**
+   * Gets all matching metadata in this DSpaceObject.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {MetadataValue[]} the matching values or an empty array.
+   */
   allMetadata(keyOrKeys: string | string[], valueFilter?: MetadataValueFilter): MetadataValue[] {
     return Metadata.all(this.metadata, keyOrKeys, valueFilter);
   }
 
-  /** Like `allMetadata`, but only returns string values. */
+  /**
+   * Like [[allMetadata]], but only returns string values.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {string[]} the matching string values or an empty array.
+   */
   allMetadataValues(keyOrKeys: string | string[], valueFilter?: MetadataValueFilter): string[] {
     return Metadata.allValues(this.metadata, keyOrKeys, valueFilter);
   }
 
-  /** Gets the first matching metadata in this DSpaceObject, or `undefined`. */
+  /**
+   * Gets the first matching MetadataValue object in this DSpaceObject, or `undefined`.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {MetadataValue} the first matching value, or `undefined`.
+   */
   firstMetadata(keyOrKeys: string | string[], valueFilter?: MetadataValueFilter): MetadataValue {
     return Metadata.first(this.metadata, keyOrKeys, valueFilter);
   }
 
-  /** Like `firstMetadata`, but only returns a string value, or `undefined`. */
+  /**
+   * Like [[firstMetadata]], but only returns a string value, or `undefined`.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {string} the first matching string value, or `undefined`.
+   */
   firstMetadataValue(keyOrKeys: string | string[], valueFilter?: MetadataValueFilter): string {
     return Metadata.firstValue(this.metadata, keyOrKeys, valueFilter);
   }
 
-  /** Checks for matching metadata in this DSpaceObject. */
+  /**
+   * Checks for a matching metadata value in this DSpaceObject.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {boolean} whether a match is found.
+   */
   hasMetadata(keyOrKeys: string | string[], valueFilter?: MetadataValueFilter): boolean {
     return Metadata.has(this.metadata, keyOrKeys, valueFilter);
   }

src/app/core/shared/metadata.model.ts

@@ -2,23 +2,27 @@ import { isEmpty } from '../../shared/empty.util';
 import { MetadataMap, MetadataValue, MetadataValueFilter } from './metadata.interfaces';
 
 /**
- * Static utility methods for working with DSpace metadata.
+ * Utility class for working with DSpace object metadata.
+ *
+ * When specifying metadata keys, wildcards are supported, so `'*'` will match all keys, `'dc.date.*'` will
+ * match all qualified dc dates, and so on. Exact keys will be evaluated (and matches returned) in the order
+ * they are given.
+ *
+ * When multiple keys in a map match a given wildcard, they are evaluated in the order they are stored in
+ * the map (alphanumeric if obtained from the REST api). If duplicate or overlapping keys are specified, the
+ * first one takes precedence. For example, specifying `['dc.date', 'dc.*', '*']` will cause any `dc.date`
+ * values to be evaluated (and returned, if matched) first, followed by any other `dc` metadata values,
+ * followed by any other (non-dc) metadata values.
  */
 export class Metadata {
 
   /**
-   * Gets all matching metadata.
+   * Gets all matching metadata in the map(s).
    *
-   * @param {MetadataMap|MetadataMap[]} mapOrMaps The source map(s). Values will only be returned from one map --
+   * @param {MetadataMap|MetadataMap[]} mapOrMaps The source map(s). When multiple maps are given, they will be
-   * the first with at least one match.
+   * checked in order, and only values from the first with at least one match will be returned.
-   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported, so `'*'` will
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see above.
-   * match all keys, `'dc.date.*'` will match all qualified dc dates, and so on. Exact keys will be evaluated
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
-   * (and matches returned) in the order they are given in the parameter. When multiple keys match a wildcard,
-   * they are evaluated in the order they are stored in the map (alphanumeric if obtained from the REST api).
-   * If duplicate or overlapping keys are specified, the first one takes precedence. For example, specifying
-   * `['dc.date', 'dc.*', '*']` will cause any `dc.date` values to be evaluated (and returned, if matched)
-   * first, followed by any other `dc` metadata values, followed by any other (non-dc) metadata values.
-   * @param {MetadataValueFilter} filter The value filter to use.
    * @returns {MetadataValue[]} the matching values or an empty array.
    */
   public static all(mapOrMaps: MetadataMap | MetadataMap[], keyOrKeys: string | string[],
@@ -43,13 +47,28 @@ export class Metadata {
     return matches;
   }
 
-  /** Like `all`, but only returns string values. */
+  /**
+   * Like [[Metadata.all]], but only returns string values.
+   *
+   * @param {MetadataMap|MetadataMap[]} mapOrMaps The source map(s). When multiple maps are given, they will be
+   * checked in order, and only values from the first with at least one match will be returned.
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see above.
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {string[]} the matching string values or an empty array.
+   */
   public static allValues(mapOrMaps: MetadataMap | MetadataMap[], keyOrKeys: string | string[],
                           filter?: MetadataValueFilter): string[] {
     return Metadata.all(mapOrMaps, keyOrKeys, filter).map((mdValue) => mdValue.value);
   }
 
-  /** Gets the first matching MetadataValue object in a map, or `undefined`. */
+  /**
+   * Gets the first matching MetadataValue object in the map(s), or `undefined`.
+   *
+   * @param {MetadataMap|MetadataMap[]} mapOrMaps The source map(s).
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see above.
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {MetadataValue} the first matching value, or `undefined`.
+   */
   public static first(mdMapOrMaps: MetadataMap | MetadataMap[], keyOrKeys: string | string[],
                       filter?: MetadataValueFilter): MetadataValue {
     const mdMaps: MetadataMap[] = mdMapOrMaps instanceof Array ? mdMapOrMaps : [ mdMapOrMaps ];
@@ -63,20 +82,40 @@ export class Metadata {
     }
   }
 
-  /** Like `first`, but only returns a string value, or `undefined`. */
+  /**
+   * Like [[Metadata.first]], but only returns a string value, or `undefined`.
+   *
+   * @param {MetadataMap|MetadataMap[]} mapOrMaps The source map(s).
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see above.
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {string} the first matching string value, or `undefined`.
+   */
   public static firstValue(mdMapOrMaps: MetadataMap | MetadataMap[], keyOrKeys: string | string[],
                            filter?: MetadataValueFilter): string {
     const value = Metadata.first(mdMapOrMaps, keyOrKeys, filter);
     return value === undefined ? undefined : value.value;
   }
 
-  /** Checks the given map for a matching value. */
+  /**
+   * Checks for a matching metadata value in the given map(s).
+   *
+   * @param {MetadataMap|MetadataMap[]} mapOrMaps The source map(s).
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see above.
+   * @param {MetadataValueFilter} filter The value filter to use. If unspecified, no filtering will be done.
+   * @returns {boolean} whether a match is found.
+   */
   public static has(mdMapOrMaps: MetadataMap | MetadataMap[], keyOrKeys: string | string[],
                     filter?: MetadataValueFilter): boolean {
     return Metadata.first(mdMapOrMaps, keyOrKeys, filter) !== undefined;
   }
 
-  /** Checks if a value matches a filter. */
+  /**
+   * Checks if a value matches a filter.
+   *
+   * @param {MetadataValue} mdValue the value to check.
+   * @param {MetadataValueFilter} filter the filter to use.
+   * @returns {boolean} whether the filter matches, or true if no filter is given.
+   */
   public static valueMatches(mdValue: MetadataValue, filter: MetadataValueFilter) {
     if (!filter) {
       return true;
@@ -98,7 +137,12 @@ export class Metadata {
     return true;
   }
 
-  /** Gets the list of keys in the map limited by, and in the order given by `keyOrKeys` */
+  /**
+   * Gets the list of keys in the map limited by, and in the order given by `keyOrKeys`.
+   *
+   * @param {MetadataMap} mdMap The source map.
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see above.
+   */
   private static resolveKeys(mdMap: MetadataMap, keyOrKeys: string | string[]): string[] {
     const inputKeys: string[] = keyOrKeys instanceof Array ? keyOrKeys : [ keyOrKeys ];
     const outputKeys: string[] = [];

src/app/shared/object-grid/search-result-grid-element/search-result-grid-element.component.ts

@@ -21,12 +21,22 @@ export class SearchResultGridElementComponent<T extends SearchResult<K>, K exten
     this.dso = this.object.dspaceObject;
   }
 
-  /** Gets all matching metadata string values from hitHighlights or dso metadata, preferring hitHighlights. */
+  /**
+   * Gets all matching metadata string values from hitHighlights or dso metadata, preferring hitHighlights.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @returns {string[]} the matching string values or an empty array.
+   */
   allMetadataValues(keyOrKeys: string | string[]): string[] {
     return Metadata.allValues([this.object.hitHighlights, this.dso.metadata], keyOrKeys);
   }
 
-  /** Gets the first matching metadata string value from hitHighlights or dso metadata, preferring hitHighlights. */
+  /**
+   * Gets the first matching metadata string value from hitHighlights or dso metadata, preferring hitHighlights.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @returns {string} the first matching string value, or `undefined`.
+   */
   firstMetadataValue(keyOrKeys: string | string[]): string {
     return Metadata.firstValue([this.object.hitHighlights, this.dso.metadata], keyOrKeys);
   }

src/app/shared/object-list/search-result-list-element/search-result-list-element.component.ts

@@ -21,12 +21,22 @@ export class SearchResultListElementComponent<T extends SearchResult<K>, K exten
     this.dso = this.object.dspaceObject;
   }
 
-  /** Gets all matching metadata string values from hitHighlights or dso metadata, preferring hitHighlights. */
+  /**
+   * Gets all matching metadata string values from hitHighlights or dso metadata, preferring hitHighlights.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @returns {string[]} the matching string values or an empty array.
+   */
   allMetadataValues(keyOrKeys: string | string[]): string[] {
     return Metadata.allValues([this.object.hitHighlights, this.dso.metadata], keyOrKeys);
   }
 
-  /** Gets the first matching metadata string value from hitHighlights or dso metadata, preferring hitHighlights. */
+  /**
+   * Gets the first matching metadata string value from hitHighlights or dso metadata, preferring hitHighlights.
+   *
+   * @param {string|string[]} keyOrKeys The metadata key(s) in scope. Wildcards are supported; see [[Metadata]].
+   * @returns {string} the first matching string value, or `undefined`.
+   */
   firstMetadataValue(keyOrKeys: string | string[]): string {
     return Metadata.firstValue([this.object.hitHighlights, this.dso.metadata], keyOrKeys);
   }