docs: improve docs of contrib.bom.utils.BomRefDiscriminator

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

Author: jkowalleck

cyclonedx/contrib/bom/utils.py

@@ -31,16 +31,17 @@
 
 class BomRefDiscriminator:
     """
-    Ensure that a collection of BomRef objects has unique, non‑empty values.
+    Ensure that a collection of :class:`cyclonedx.model.bom_ref.BomRef` objects has unique, non‑empty values.
 
     The discriminator inspects the provided BomRef instances and assigns new,
     automatically generated identifiers to any BomRef whose value is missing
-    or duplicates another. Original values are preserved so they can be
-    restored later via `reset()` or by using this class as a context manager.
+    or duplicates another.
+    Original values are preserved so they can be restored later via :meth:`reset()` or by using this class as a context manager.
     """
 
     def __init__(self, bomrefs: Iterable['BomRef'], prefix: str = 'BomRef') -> None:
-        # do not use dict/set here, different BomRefs with same value have same hash and would shadow each other
+        # NOTE: do not use dict/set here, different BomRefs with same value
+        #       have same hash and would shadow each other.
         self._bomrefs = tuple((bomref, bomref.value) for bomref in bomrefs)
         self._prefix = prefix
 
@@ -52,10 +53,11 @@ def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
 
     def discriminate(self) -> None:
         """
-        Enforce uniqueness across all BomRef values.
+        Enforce uniqueness across all :attr:`cyclonedx.model.bom_ref.BomRef.value`.
 
-        Any BomRef whose value is `None` or duplicates a previously encountered
-        value is assigned a newly generated unique identifier.
+        .. note::
+           Any BomRef whose value is ``None`` or duplicates a previously encountered
+           value is assigned a newly generated unique identifier.
         """
         known_values = []
         for bomref, _ in self._bomrefs:
@@ -67,7 +69,7 @@ def discriminate(self) -> None:
 
     def reset(self) -> None:
         """
-        Restore all BomRef values to their original state.
+        Restore all :attr:`cyclonedx.model.bom_ref.BomRef.value` to their original state.
         """
         for bomref, original_value in self._bomrefs:
             bomref.value = original_value
@@ -81,9 +83,9 @@ def from_bom(cls, bom: 'Bom', prefix: str = 'BomRef') -> 'BomRefDiscriminator':
         Create a discriminator for all BomRefs contained within a BOM.
 
         This includes BomRefs from
-        - components
-        - services
-        - vulnerabilities
+          * components
+          * services
+          * vulnerabilities
         """
         return cls(chain(
             map(lambda c: c.bom_ref, bom._get_all_components()),