Add doc strings to all public types

Docs are limited to links until I have clarity on license compatibility with upstream

src/definitions.rs

@@ -3,10 +3,10 @@ use std::convert::{TryFrom, TryInto};
 use serde::{Deserialize, Serialize};
 use url::Url;
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#311-acknowledgments-type
 pub(crate) type AcknowledgmentsT = Vec<Acknowledgment>;
 
 // TODO: with at least 1 and at most 4 properties
+/// [Acknowledgment](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#311-acknowledgments-type)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct Acknowledgment {
@@ -16,7 +16,7 @@ pub struct Acknowledgment {
     pub urls: Option<Vec<Url>>,
 }
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#312-branches-type
+/// [Branches](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#312-branches-type)
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct BranchesT(pub Vec<Branch>);
 
@@ -41,6 +41,7 @@ impl TryFrom<&Branch> for ProductIdT {
     }
 }
 
+/// [Branch](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3121-branches-type---branches)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct Branch {
@@ -51,6 +52,7 @@ pub struct Branch {
     pub branches: Option<BranchesT>,
 }
 
+/// [Branch Category](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3122-branches-type---category)
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "snake_case")]
 pub enum BranchCategory {
@@ -67,7 +69,7 @@ pub enum BranchCategory {
     Vendor,
 }
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#313-full-product-name-type
+/// [Full Product Name](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#313-full-product-name-type)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct FullProductName {
@@ -76,7 +78,7 @@ pub struct FullProductName {
     pub product_identification_helper: Option<ProductIdentificationHelper>,
 }
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3133-full-product-name-type---product-identification-helper
+/// [Product Identification Helper](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3133-full-product-name-type---product-identification-helper)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct ProductIdentificationHelper {
@@ -89,24 +91,28 @@ pub struct ProductIdentificationHelper {
     pub x_generic_uris: Option<Vec<Url>>,
 }
 
+/// [Hashes](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#31332-full-product-name-type---product-identification-helper---hashes)
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct HashCollection {
     pub file_hashes: Vec<HashValue>,
     pub file_name: String,
 }
 
+/// [Hashes](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#31332-full-product-name-type---product-identification-helper---hashes)
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct HashValue {
+    // TODO: Validation - These values are derived from the currently supported digests OpenSSL [OPENSSL]. Leading dashs were removed.
     pub algorithm: String,
+    // TODO: Validation  ^[0-9a-fA-F]{32,}$
     pub value: String,
 }
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#314-language-type
+/// [LangT](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#314-language-type)
 pub(crate) type LangT = String; // TODO: Constrain/validate
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#315-notes-type
 pub(crate) type NotesT = Vec<Note>;
 
+/// [Notes](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#315-notes-type)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct Note {
@@ -116,6 +122,7 @@ pub struct Note {
     pub title: Option<String>,
 }
 
+/// [Notes](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#315-notes-type)
 #[derive(Serialize, Deserialize, Debug)]
 #[serde(rename_all = "snake_case")]
 pub enum NoteCategory {
@@ -128,22 +135,22 @@ pub enum NoteCategory {
     Summary,
 }
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#316-product-group-id-type
+/// [Product Group ID](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#316-product-group-id-type)
 pub(crate) type ProductGroupIdT = String;
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#317-product-groups-type
+/// [Product Groups](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#317-product-groups-type)
 pub(crate) type ProductGroupsT = Vec<ProductGroupIdT>;
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#318-product-id-type
+/// [Product IDs](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#318-product-id-type)
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct ProductIdT(pub(crate) String);
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#319-products-type
+/// [Products](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#319-products-type)
 pub(crate) type ProductsT = Vec<ProductIdT>;
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3110-references-type
 pub(crate) type ReferencesT = Vec<Reference>;
 
+/// [References](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3110-references-type)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct Reference {
@@ -152,6 +159,7 @@ pub struct Reference {
     pub category: Option<ReferenceCategory>,
 }
 
+/// [References](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3110-references-type)
 #[derive(Serialize, Deserialize, Debug)]
 #[serde(rename_all = "snake_case")]
 pub enum ReferenceCategory {
@@ -160,6 +168,6 @@ pub enum ReferenceCategory {
     RefSelf,
 }
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3111-version-type
 // TODO: Contraint/validation
+/// [Version](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3111-version-type)
 pub(crate) type VersionT = String;

src/document.rs

@@ -22,6 +22,7 @@ pub struct Document {
     pub source_lang: Option<LangT>,
 }
 
+/// [CSAF Version](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3214-document-property---csaf-version)
 #[derive(Serialize, Deserialize, Debug)]
 pub enum CsafVersion {
     #[serde(rename = "2.0")]
@@ -73,6 +74,7 @@ pub struct Generator {
     pub date: Option<DateTime<Utc>>,
 }
 
+/// [Generator Engine](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#321123-document-property---tracking---generator)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct Engine {
@@ -136,6 +138,7 @@ pub struct Tlp {
     pub url: Option<Url>,
 }
 
+/// [TLP](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#32152-document-property---distribution---tlp)
 #[derive(Serialize, Deserialize, Debug)]
 pub enum TlpLabel {
     AMBER,

src/interop.rs

@@ -24,6 +24,11 @@ use url::Url;
 //
 // Each RUSTSEC advisory applies to only one 'product' - in this case crate, referred to as Advisory.package
 
+/// Provides a conversion from a [rustsec::Advisory] to a `Csaf` implementing the [VEX profile](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#45-profile-5-vex)
+///
+/// Currently functioning and passes validation as a CSAF. Is not strictly valid VEX. VEX requires that each `known_not_affected` product
+/// have an impact statement listed as a [Threat](crate::vulnerability::Threat) with [ThreatCategory](crate::vulnerability::ThreatCategory) `Impact`.
+/// RustSec does not have any metadata that "contain(s) a a description why the vulnerability cannot be exploited".
 impl From<Advisory> for Csaf {
     fn from(input: Advisory) -> Self {
         let advisory_date = input.metadata.date;

src/lib.rs

@@ -4,6 +4,10 @@
 //! based on the [v2.0 editor draft](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md). Should be
 //! considered strictly less-strict than the spec right now - valid CSAF should deserialize successfully, but invalid CSAF may also
 //! succeed and the library may generate invalid CSAF.
+//!
+//! Documentaiton is provided as links to the upstream CSAF repository. This is because it is unclear to me if the upstream license
+//! allows for inclusion of the documentation in to this repository directly. Inclusion of details from upstream
+//!  would be more usable, but without guidance on license compatibility I'm only comfortable providing links for now.
 
 use serde::{Deserialize, Serialize};
 
@@ -18,9 +22,11 @@ use vulnerability::Vulnerability;
 
 pub mod definitions;
 
-pub mod interop;
+mod interop;
 
 /// [Top level CSAF structure definition](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#32-properties)
+///
+/// Interoperatbility with [RustSec](https://rustsec.org/) advisories is profivided by a `From` implementation.
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct Csaf {

src/product_tree.rs

@@ -2,7 +2,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::definitions::{BranchesT, FullProductName, ProductGroupIdT, ProductIdT};
 
-// https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#322-product-tree-property
+/// [Product Tree](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#322-product-tree-property)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct ProductTree {
@@ -12,6 +12,7 @@ pub struct ProductTree {
     pub relationships: Option<Vec<Relationship>>,
 }
 
+/// [Product Groups](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3223-product-tree-property---product-groups)
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct ProductGroup {
@@ -20,6 +21,7 @@ pub struct ProductGroup {
     pub summary: Option<String>,
 }
 
+/// [Relationships](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3224-product-tree-property---relationships)
 #[derive(Serialize, Deserialize, Debug)]
 pub struct Relationship {
     pub category: RelationshipCategory,
@@ -28,6 +30,7 @@ pub struct Relationship {
     pub relates_to_product_reference: ProductIdT,
 }
 
+/// [Relationships](https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/prose/csaf-v2-editor-draft.md#3224-product-tree-property---relationships)
 #[derive(Serialize, Deserialize, Debug)]
 #[serde(rename_all = "snake_case")]
 pub enum RelationshipCategory {