doc: added documentation

Signed-off-by: Paul Horton <phorton@sonatype.com>

Author: madpah

cyclonedx/model/component.py

@@ -28,8 +28,10 @@
 
 class ComponentType(Enum):
     """
-    Enum object that defines the permissible 'types' for a Component according to the CycloneDX
-    schemas.
+    Enum object that defines the permissible 'types' for a Component according to the CycloneDX schema.
+
+    .. note::
+        See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.3/#type_classification
     """
     APPLICATION = 'application'
     CONTAINER = 'container'
@@ -43,7 +45,10 @@ class ComponentType(Enum):
 
 class Component:
     """
-    An object that mirrors the Component type in the CycloneDX schema.
+    This is our internal representation of a Component within a Bom.
+
+    .. note::
+        See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.3/#type_component
     """
     _type: ComponentType
     _name: str
@@ -65,52 +70,147 @@ def __init__(self, name: str, version: str, qualifiers: str = None,
         self._vulnerabilites = []
 
     def add_vulnerability(self, vulnerability: Vulnerability):
+        """
+        Add a Vulnerability to this Component.
+
+        Args:
+            vulnerability:
+                `cyclonedx.model.vulnerability.Vulnerability` instance to add to this Component.
+
+        Returns:
+            None
+        """
         self._vulnerabilites.append(vulnerability)
 
     def get_author(self) -> str:
+        """
+        Get the author of this Component.
+
+        Returns:
+            Declared author of this Component as `str`.
+        """
         return self._author
 
     def get_description(self) -> str:
+        """
+        Get the description of this Component.
+
+        Returns:
+            Declared description of this Component as `str`.
+        """
         return self._description
 
     def get_license(self) -> str:
+        """
+        Get the license of this Component.
+
+        Returns:
+            Declared license of this Component as `str`.
+        """
         return self._license
 
     def get_name(self) -> str:
+        """
+        Get the name of this Component.
+
+        Returns:
+            Declared name of this Component as `str`.
+        """
         return self._name
 
     def get_purl(self) -> str:
+        """
+        Get the PURL for this Component.
+
+        Returns:
+            PackageURL that reflects this Component as `str`.
+        """
         base_purl = 'pkg:{}/{}@{}'.format(PURL_TYPE_PREFIX, self._name, self._version)
         if self._qualifiers:
             base_purl = '{}?{}'.format(base_purl, self._qualifiers)
         return base_purl
 
     def get_type(self) -> ComponentType:
+        """
+        Get the type of this Component.
+
+        Returns:
+            Declared type of this Component as `ComponentType`.
+        """
         return self._type
 
     def get_version(self) -> str:
+        """
+        Get the version of this Component.
+
+        Returns:
+            Declared version of this Component as `str`.
+        """
         return self._version
 
     def get_vulnerabilities(self) -> List[Vulnerability]:
+        """
+        Get all the Vulnerabilities for this Component.
+
+        Returns:
+             List of `Vulnerability` objects assigned to this Component.
+        """
         return self._vulnerabilites
 
     def has_vulnerabilities(self) -> bool:
+        """
+        Does this Component have any vulnerabilities?
+
+        Returns:
+             `True` if this Component has 1 or more vulnerabilities, `False` otherwise.
+        """
         return len(self._vulnerabilites) != 0
 
     def set_author(self, author: str):
+        """
+        Set the author of this Component.
+
+        Args:
+            author:
+                `str` to set the author to
+
+        Returns:
+            None
+        """
         self._author = author
 
     def set_description(self, description: str):
+        """
+        Set the description of this Component.
+
+        Args:
+            description:
+                `str` to set the description to
+
+        Returns:
+            None
+        """
         self._description = description
 
     def set_license(self, license_str: str):
+        """
+        Set the license for this Component.
+
+        Args:
+            license_str:
+                `str` to set the license to
+
+        Returns:
+            None
+        """
         self._license = license_str
 
     def to_package_url(self) -> PackageURL:
         """
         Return a PackageURL representation of this Component.
 
-        :return: PackageURL
+        Returns:
+            `packageurl.PackageURL` instance which represents this Component.
         """""
         return PackageURL(
             type=PURL_TYPE_PREFIX,

cyclonedx/model/vulnerability.py

@@ -24,15 +24,19 @@
 
 """
 This set of classes represents the data that is possible under the CycloneDX extension
-schema for Vulnerabilties (version 1.0).
+schema for Vulnerabilities (version 1.0).
 
-See: https://github.com/CycloneDX/specification/blob/master/schema/ext/vulnerability-1.0.xsd
+.. note::
+    See the CycloneDX Schema extension definition https://cyclonedx.org/ext/vulnerability/.
 """
 
 
 class VulnerabilitySourceType(Enum):
     """
-    Represents <xs:simpleType name="scoreSourceType">
+    Enum object that defines the permissible source types for a Vulnerability.
+
+    .. note::
+        See `scoreSourceType` in https://github.com/CycloneDX/specification/blob/master/schema/ext/vulnerability-1.0.xsd
     """
     CVSS_V2 = 'CVSSv2'
     CVSS_V3 = 'CVSSv3'
@@ -42,6 +46,17 @@ class VulnerabilitySourceType(Enum):
 
     @staticmethod
     def get_from_vector(vector: str):
+        """
+        Attempt to derive the correct SourceType from an attack vector.
+
+        For example, often attack vector strings are prefixed with the scheme in question - such
+        that __CVSS:3.0/AV:L/AC:L/PR:N/UI:R/S:C/C:L/I:N/A:N__ would be the vector
+        __AV:L/AC:L/PR:N/UI:R/S:C/C:L/I:N/A:N__ under the __CVSS 3__ scheme.
+
+        Returns:
+            Always returns an instance of `VulnerabilitySourceType`. `VulnerabilitySourceType.OTHER` is returned if the
+            scheme is not obvious or known to us.
+        """
         if vector.startswith('CVSS:3.'):
             return VulnerabilitySourceType.CVSS_V3
         elif vector.startswith('CVSS:2.'):
@@ -53,12 +68,13 @@ def get_from_vector(vector: str):
 
     def get_localised_vector(self, vector: str) -> str:
         """
-        This method will remove any Source Scheme type from the supplied vector.
+        This method will remove any Source Scheme type from the supplied vector, returning just the vector.
 
-        For example if VulnerabilitySourceType.OWASP
+        .. Note::
+            Currently supports CVSS 3.x, CVSS 2.x and OWASP schemes.
 
-        :param vector:
-        :return:
+        Returns:
+            The vector without any scheme prefix as a `str`.
         """
         if self == VulnerabilitySourceType.CVSS_V3 and vector.startswith('CVSS:3.'):
             return re.sub('^CVSS:3\\.\\d/?', '', vector)
@@ -74,7 +90,10 @@ def get_localised_vector(self, vector: str) -> str:
 
 class VulnerabilitySeverity(Enum):
     """
-    Represents <xs:simpleType name="severityType">
+    Enum object that defines the permissible severities for a Vulnerability.
+
+    .. note::
+        See `severityType` in https://github.com/CycloneDX/specification/blob/master/schema/ext/vulnerability-1.0.xsd
     """
     NONE = 'None'
     LOW = 'Low'
@@ -85,6 +104,15 @@ class VulnerabilitySeverity(Enum):
 
     @staticmethod
     def get_from_cvss_scores(scores: tuple = None):
+        """
+        Derives the Severity of a Vulnerability from it's declared CVSS scores.
+
+        Args:
+            scores: A `tuple` of CVSS scores. CVSS scoring system allows for up to three separate scores.
+
+        Returns:
+            Always returns an instance of `VulnerabilitySeverity`.
+        """
         if type(scores) is float:
             scores = (scores,)
 
@@ -107,7 +135,10 @@ def get_from_cvss_scores(scores: tuple = None):
 
 class VulnerabilityRating:
     """
-    Represents <xs:complexType name="scoreType">
+    Class that models the `scoreType` complex element in the Vulnerability extension schema.
+
+    .. note::
+        See `scoreType` in https://github.com/CycloneDX/specification/blob/master/schema/ext/vulnerability-1.0.xsd
     """
     _score_base: float
     _score_impact: float
@@ -130,18 +161,48 @@ def __init__(self, score_base: float = None, score_impact: float = None, score_e
             self._vector = vector
 
     def get_base_score(self) -> float:
+        """
+        Get the base score of this VulnerabilityRating.
+
+        Returns:
+           Declared base score of this VulnerabilityRating as `float`.
+        """
         return self._score_base
 
     def get_impact_score(self) -> float:
+        """
+        Get the impact score of this VulnerabilityRating.
+
+        Returns:
+           Declared impact score of this VulnerabilityRating as `float`.
+        """
         return self._score_impact
 
     def get_exploitability_score(self) -> float:
+        """
+        Get the exploitability score of this VulnerabilityRating.
+
+        Returns:
+           Declared exploitability score of this VulnerabilityRating as `float`.
+        """
         return self._score_exploitability
 
     def get_severity(self) -> Union[VulnerabilitySeverity, None]:
+        """
+        Get the severity score of this VulnerabilityRating.
+
+        Returns:
+           Declared severity of this VulnerabilityRating as `VulnerabilitySeverity` or `None`.
+        """
         return self._severity
 
     def get_method(self) -> Union[VulnerabilitySourceType, None]:
+        """
+        Get the source method of this VulnerabilitySourceType.
+
+        Returns:
+           Declared source method of this VulnerabilitySourceType as `VulnerabilitySourceType` or `None`.
+        """
         return self._method
 
     def get_vector(self) -> Union[str, None]:

cyclonedx/output/__init__.py

@@ -14,6 +14,11 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Set of classes and methods for outputting our libraries internal Bom model to CycloneDX documents in varying formats
+and according to different versions of the CycloneDX schema standard.
+"""
+
 import importlib
 import os
 from abc import ABC, abstractmethod

cyclonedx/parser/__init__.py

@@ -14,6 +14,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Set of classes and methods which allow for quick creation of a Bom instance from your environment or Python project.
+
+Use a Parser instead of programmatically creating a Bom as a developer.
+"""
+
 from abc import ABC
 from typing import List