docs: API doc clean up and improvement

sdk/src/assertions/actions.rs

@@ -29,7 +29,7 @@ use crate::{
 const ASSERTION_CREATION_VERSION: usize = 2;
 pub const CAI_INGREDIENT_IDS: &str = "org.cai.ingredientIds";
 
-/// Specification defined C2PA actions
+/// C2PA actions defined in the C2PA specification.
 pub mod c2pa_action {
     /// Changes to tone, saturation, etc.
     pub const COLOR_ADJUSTMENTS: &str = "c2pa.color_adjustments";
@@ -126,7 +126,7 @@ impl From<ClaimGeneratorInfo> for SoftwareAgent {
 /// along with possible other information such as what software performed
 /// the action.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_actions>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions>.
 #[derive(Deserialize, Serialize, Clone, Debug, Default, PartialEq)]
 pub struct Action {
     /// The label associated with this action. See ([`c2pa_action`]).
@@ -273,22 +273,23 @@ impl Action {
     }
 
     /// Returns a digitalSourceType as defined at <https://cv.iptc.org/newscodes/digitalsourcetype/>.
+    // QUESTION: Keep in docs?
     pub fn source_type(&self) -> Option<&str> {
         self.source_type.as_deref()
     }
 
     /// Returns the list of related actions.
     ///
     /// This is only present in C2PA v2.
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_related>.
+    /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_related_actions>.
     pub fn related(&self) -> Option<&[Action]> {
         self.related.as_deref()
     }
 
     /// Returns the reason why this action was performed.
     ///
     /// This is only present in C2PA v2.
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_reason>.
+    /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_reason>.
     pub fn reason(&self) -> Option<&str> {
         self.reason.as_deref()
     }
@@ -407,7 +408,7 @@ impl Action {
     /// Sets the list of related actions.
     ///
     /// This is only present in C2PA v2.
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_related>.
+    /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_related_actions>.
     pub fn set_related(mut self, related: Option<&Vec<Action>>) -> Self {
         self.related = related.cloned();
         self
@@ -416,7 +417,7 @@ impl Action {
     /// Sets the reason why this action was performed.
     ///
     /// This is only present in C2PA v2.
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_reason>.
+    /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_reason>.
     pub fn set_reason<S: Into<String>>(mut self, reason: S) -> Self {
         self.reason = Some(reason.into());
         self
@@ -492,7 +493,7 @@ impl ActionTemplate {
 /// what took place on the asset, when it took place, along with possible
 /// other information such as what software performed the action.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_actions>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions>.
 #[derive(Deserialize, Serialize, Debug, PartialEq)]
 #[non_exhaustive]
 pub struct Actions {
@@ -519,7 +520,7 @@ pub struct Actions {
 impl Actions {
     /// Label prefix for an [`Actions`] assertion.
     ///
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_actions>.
+    /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions>.
     pub const LABEL: &'static str = labels::ACTIONS;
 
     /// Creates a new [`Actions`] assertion struct.

sdk/src/assertions/creative_work.rs

@@ -31,7 +31,7 @@ pub struct CreativeWork(SchemaDotOrg);
 impl CreativeWork {
     /// Label prefix for a creative work assertion.
     ///
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_creative_work>.
+    /// See <https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_creative_work>.
     pub const LABEL: &'static str = labels::CREATIVE_WORK;
 
     pub fn new() -> CreativeWork {

sdk/src/assertions/exif.rs

@@ -23,10 +23,11 @@ use crate::{
     Error, Result,
 };
 
-/// The EXIF assertion as defined in the C2PA spec section 17.13
-///  See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_exif_information>
+/// The EXIF assertion (part of CAWG metadata specification).
 ///
-/// This does not yet define or validate individual fields, but will ensure the correct assertion structure
+/// This does not yet define or validate individual fields, but will ensure the correct assertion structure.
+// NOTE: Hidden because it's now part of standard metadata assertions.
+#[doc(hidden)]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct Exif {
     #[serde(rename = "@context", skip_serializing_if = "Option::is_none")]

sdk/src/assertions/ingredient.rs

@@ -29,15 +29,18 @@ use crate::{
 
 const ASSERTION_CREATION_VERSION: usize = 3;
 
-// Used to differentiate a parent from a component
+/// The relationship of the ingredient to the current asset.
 #[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
 #[cfg_attr(feature = "json_schema", derive(JsonSchema))]
 pub enum Relationship {
+    /// The current asset is derived from this ingredient.
     #[serde(rename = "parentOf")]
     ParentOf,
+    /// The current asset is a part of this ingredient.
     #[serde(rename = "componentOf")]
     #[default]
     ComponentOf,
+    /// The ingredient was used as an input to a computational process to create or modify the asset.
     #[serde(rename = "inputTo")]
     InputTo,
 }
@@ -85,7 +88,7 @@ impl Serialize for Ingredient {
 impl Ingredient {
     /// Label prefix for an ingredient assertion.
     ///
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_ingredient>.
+    /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#ingredient_assertion>.
     pub const LABEL: &'static str = labels::INGREDIENT;
 
     pub fn new(title: &str, format: &str, instance_id: &str, document_id: Option<&str>) -> Self {

sdk/src/assertions/labels.rs

@@ -17,21 +17,21 @@
 //!
 //! These constants do not include version suffixes.
 //!
-//! See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_c2pa_standard_assertions>.
+//! See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_c2pa_standard_assertions>.
 
 /// Label prefix for a claim assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_overview_4>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_overview_4>.
 pub const CLAIM: &str = "c2pa.claim";
 
 /// Label prefix for an assertion metadata assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_metadata_about_assertions>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_metadata_about_assertions>.
 pub const ASSERTION_METADATA: &str = "c2pa.assertion.metadata";
 
 /// Label prefix for a data hash assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_data_hash>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_data_hash>.
 pub const DATA_HASH: &str = "c2pa.hash.data";
 
 /// Label prefix for a box hash assertion.
@@ -41,7 +41,7 @@ pub const BOX_HASH: &str = "c2pa.hash.boxes";
 
 /// Label prefix for a BMFF-based hash assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_bmff_based_hash>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_bmff_based_hash>.
 pub const BMFF_HASH: &str = "c2pa.hash.bmff";
 
 /// Label prefix for a collection hash assertion.
@@ -51,72 +51,72 @@ pub const COLLECTION_HASH: &str = "c2pa.hash.collection.data";
 
 /// Label prefix for a soft binding assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_soft_binding_2>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_soft_binding_2>.
 pub const SOFT_BINDING: &str = "c2pa.soft-binding";
 
 /// Label prefix for a cloud data assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_cloud_data>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_cloud_data>.
 pub const CLOUD_DATA: &str = "c2pa.cloud-data";
 
 /// Label prefix for a thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const THUMBNAIL: &str = "c2pa.thumbnail";
 
 /// Label prefix for a claim thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const CLAIM_THUMBNAIL: &str = "c2pa.thumbnail.claim";
 
 /// Label prefix for an ingredient thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const INGREDIENT_THUMBNAIL: &str = "c2pa.thumbnail.ingredient";
 
 /// Label prefix for a JPEG claim thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const JPEG_CLAIM_THUMBNAIL: &str = "c2pa.thumbnail.claim.jpeg";
 
 /// Label prefix for a JPEG ingredient thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const JPEG_INGREDIENT_THUMBNAIL: &str = "c2pa.thumbnail.ingredient.jpeg";
 
 /// Label prefix for a PNG claim thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const PNG_CLAIM_THUMBNAIL: &str = "c2pa.thumbnail.claim.png";
 
 /// Label prefix for a PNG ingredient thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const PNG_INGREDIENT_THUMBNAIL: &str = "c2pa.thumbnail.ingredient.png";
 
 /// Label prefix for a SVG claim thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const SVG_CLAIM_THUMBNAIL: &str = "c2pa.thumbnail.claim.svg";
 
 /// Label prefix for a SVG ingredient thumbnail assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_thumbnail>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_thumbnail>.
 pub const SVG_INGREDIENT_THUMBNAIL: &str = "c2pa.thumbnail.ingredient.svg";
 
 /// Label prefix for an actions assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_actions>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions>.
 pub const ACTIONS: &str = "c2pa.actions";
 
 /// Label prefix for an ingredient assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_ingredient>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_ingredient>.
 pub const INGREDIENT: &str = "c2pa.ingredient";
 
 /// Label prefix for a depthmap assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_depthmap>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_depthmap>.
 pub const DEPTHMAP: &str = "c2pa.depthmap";
 
 /// Label prefix for a asset type assertion.
@@ -126,32 +126,38 @@ pub const ASSET_TYPE: &str = "c2pa.asset-type";
 
 /// Label prefix for a GDepth depthmap assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_gdepth_depthmap>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_gdepth_depthmap>.
 pub const DEPTHMAP_GDEPTH: &str = "c2pa.depthmap.GDepth";
 
 /// Label prefix for an EXIF information assertion.
+/// Hidden because it's now part of standard metadata assertions.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_exif_information>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_exif_information>.
+#[doc(hidden)]
 pub const EXIF: &str = "stds.exif";
 
 /// Label prefix for an IPTC photo metadata assertion.
+/// Hidden because it's now part of standard metadata assertions.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_iptc_photo_metadata>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_iptc_photo_metadata>.
+#[doc(hidden)]
 pub const IPTC_PHOTO_METADATA: &str = "stds.iptc.photo-metadata";
 
 /// Label prefix for any assertion based on a schema.org grammar.
+/// Hidden because it's now part of standard metadata assertions.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_use_of_schema_org>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_use_of_schema_org>.
+#[doc(hidden)]
 pub const SCHEMA_ORG: &str = "schema.org";
 
 /// Label prefix for a claim review assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_claim_review>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_claim_review>.
 pub const CLAIM_REVIEW: &str = "stds.schema-org.ClaimReview";
 
 /// Label prefix for a creative work assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_creative_work>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_creative_work>.
 pub const CREATIVE_WORK: &str = "stds.schema-org.CreativeWork";
 
 /// Label prefix for a timestamp assertion.
@@ -171,10 +177,10 @@ pub(crate) const DATABOX_STORE: &str = "c2pa.databoxes";
 /// the label would consist of an incremented version number, for example
 /// moving from `c2pa.ingredient` to `c2pa.ingredient.v2`.
 ///
-/// If such a suffix exists (`.v(integer)`), that will be returned; otherwise,
-/// `None` will be returned.
+/// If such a suffix exists (`.v(integer)`), return that; otherwise,
+/// return `None`.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_versioning>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_versioning>.
 ///
 /// # Examples
 ///

sdk/src/assertions/metadata.rs

@@ -50,7 +50,7 @@ pub struct Metadata {
 impl Metadata {
     /// Label prefix for an assertion metadata assertion.
     ///
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_metadata_about_assertions>.
+    /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_metadata_about_assertions>.
     pub const LABEL: &'static str = labels::ASSERTION_METADATA;
 
     pub fn new() -> Self {
@@ -275,7 +275,7 @@ pub enum ReviewCode {
 
 /// A rating on an Assertion.
 ///
-/// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_claim_review>.
+/// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_review_ratings>.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)]
 #[cfg_attr(feature = "json_schema", derive(JsonSchema))]
 pub struct ReviewRating {

sdk/src/assertions/schema_org.rs

@@ -214,7 +214,7 @@ pub mod tests {
     const USER_ID: &str = "1234567890";
     const IDENTITY_URI: &str = "https://some_identity/service/";
 
-    // example review rating from
+    // Example review rating from
     // https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_claim_review
     const RATING: &str = r#"{
         "@context": "http://schema.org",

sdk/src/assertions/timestamp.rs

@@ -30,7 +30,7 @@ pub struct TimeStamp(HashMap<String, ByteBuf>);
 impl TimeStamp {
     /// Label prefix for an [`Actions`] assertion.
     ///
-    /// See <https://c2pa.org/specifications/specifications/1.0/specs/C2PA_Specification.html#_actions>.
+    /// See <https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions>.
     pub const LABEL: &'static str = labels::TIMESTAMP;
 
     pub fn new(label: &str, timestamp: &[u8]) -> Self {

sdk/src/builder.rs

@@ -161,10 +161,10 @@ impl AssertionDefinition {
 
 /// Use a Builder to add a signed manifest to an asset.
 ///
-/// # Example: Building and signing a manifest:
+/// # Example: Building and signing a manifest
 ///
-///
-/// # use c2pa::Result;
+/// ```
+/// use c2pa::Result;
 /// use std::path::PathBuf;
 ///
 /// use c2pa::{create_signer, Builder, SigningAlg};
@@ -209,6 +209,7 @@ impl AssertionDefinition {
 /// )?;
 /// # Ok(())
 /// # }
+/// ```
 #[skip_serializing_none]
 #[derive(Debug, Default, Deserialize, Serialize)]
 #[cfg_attr(feature = "json_schema", derive(JsonSchema))]

sdk/src/external_manifest.rs

@@ -22,6 +22,7 @@ use crate::Result;
 // assertions in the active manifest.  You cannot add or remove assertions. Special
 // assertions like hash assertions (c2pa.hash.{data | boxes | bmff | bmff.v2}), ingredients,
 // or action assertions cannot be changed.
+#[doc(hidden)]
 pub trait ManifestPatchCallback {
     fn patch_manifest(&self, manifest_store: &[u8]) -> Result<Vec<u8>>;
 }

sdk/src/ingredient.rs

@@ -510,11 +510,13 @@ impl Ingredient {
     }
 
     /// Return an immutable reference to the ingredient resources.
+    #[doc(hidden)]
     pub fn resources(&self) -> &ResourceStore {
         &self.resources
     }
 
     /// Return an mutable reference to the ingredient resources.
+    #[doc(hidden)]
     pub fn resources_mut(&mut self) -> &mut ResourceStore {
         &mut self.resources
     }