docs: document Models.BomLink* (#857)

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>
CycloneDX · Jun 27, 2023 · 9e5de07 · 9e5de07
1 parent 8a196ea
commit 9e5de07
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 4 deletions.
diff --git a/HISTORY.md b/HISTORY.md
@@ -32,7 +32,7 @@ Added functionality regarding [_CycloneDX_ BOM-Link](https://cyclonedx.org/capab
     * Enum `Vulnerability.RatingMethod` got new members ([#505] via [#843])  
       New: `CVSSv4`, `SSVC`
   * Namespace `Models`
-    * New classes `BomLinkDocument` and `BomLinkDocument` to represent _CycloneDX_ BOM-Link (via [#843], [#856]) 
+    * New classes `BomLinkDocument` and `BomLinkDocument` to represent _CycloneDX_ BOM-Link (via [#843], [#856], [#857])
     * New type `BomLink` to represent _CycloneDX_ BOM-Link (via [#843], [#856])
   * Namespace `Spec`
     * Enum `Version` got new member `v1dot5` to reflect _CycloneDX_ Specification-1.5 ([#505] via [#843])
@@ -52,6 +52,7 @@ Added functionality regarding [_CycloneDX_ BOM-Link](https://cyclonedx.org/capab
 [#841]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/841
 [#843]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/843
 [#856]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/856
+[#857]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/857
 
 ## 2.1.0 -- 2023-06-10
 

diff --git a/src/models/bomLink.ts b/src/models/bomLink.ts
@@ -24,12 +24,19 @@ abstract class BomLinkBase implements Stringable, Comparable<Stringable> {
   /* @ts-expect-error TS2564 */
   #value: string
 
+  /** @internal */
   protected abstract _isValid (value: any): boolean
 
+  /**
+   * @throws {@link RangeError} if value is invalid
+   */
   constructor (value: string) {
     this.value = value
   }
 
+  /**
+   * @throws {@link RangeError} if value is invalid
+   */
   set value (value: string) {
     if (!this._isValid(value)) {
       throw new RangeError('invalid value')
@@ -51,41 +58,54 @@ abstract class BomLinkBase implements Stringable, Comparable<Stringable> {
 }
 
 /**
+ * Descriptor for another BOM document.
+ *
  * See [the docs](https://cyclonedx.org/capabilities/bomlink/)
  */
 export class BomLinkDocument extends BomLinkBase {
   /* regular expressions were taken from the CycloneDX schema definitions. */
   static #pattern = /^urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[1-9][0-9]*$/
 
+  /**
+   * Whether the `value` is a valid descriptor for another BOM document.
+   */
   static isValid (value: any): boolean {
     return typeof value === 'string' &&
-      BomLinkDocument.#pattern.test(value)
+      this.#pattern.test(value)
   }
 
+  /** @internal */
   protected _isValid (value: any): boolean {
     return BomLinkDocument.isValid(value)
   }
 }
 
 /**
+ * Descriptor for an element in a BOM document.
+ *
  * See [the docs](https://cyclonedx.org/capabilities/bomlink/)
  */
 export class BomLinkElement extends BomLinkBase {
   /* regular expressions were taken from the CycloneDX schema definitions. */
   static #pattern = /^urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[1-9][0-9]*#.+$/
 
+  /**
+   * Whether the `value` is a valid descriptor for an element in a BOM document.
+   */
   static isValid (value: any): boolean {
     return typeof value === 'string' &&
-      BomLinkElement.#pattern.test(value)
+      this.#pattern.test(value)
   }
 
+  /** @internal */
   protected _isValid (value: any): boolean {
     return BomLinkElement.isValid(value)
   }
 }
 
 /**
+ * Either {@link BomLinkDocument} or {@link BomLinkElement}.
+ *
  * See [the docs](https://cyclonedx.org/capabilities/bomlink/)
- * @see {@link isBomLink}
  */
 export type BomLink = BomLinkDocument | BomLinkElement