commit 87fc428232ce1e77de8cd136f3bbbdc374dd1447
parent f68d131d26660da837b2530c5224bf6757339eb0
Author: Gavin Peacock <gpeacock@adobe.com>
Date: Thu, 26 May 2022 10:07:47 -0700
Improve documentation (#14)
* Change ring license hash to decimal
to avoid false error report
* cleanup use declarations
* Add read Actions Assertion example
* Limited Internal Assertion doc header
* Make DataHash, Ingredient and Thumbnail assertions private
* Edit a few doc comments for style
* A few more stylistic tweaks
* Marks module allow[dead_code] instead of individual methods
these will later become public
Co-authored-by: Eric Scouten <scouten@adobe.com>
Diffstat:
7 files changed, 41 insertions(+), 29 deletions(-)
diff --git a/sdk/examples/client/client.rs b/sdk/examples/client/client.rs
@@ -16,8 +16,7 @@
use anyhow::Result;
use c2pa::{
- assertions::labels,
- assertions::{c2pa_action, Action, Actions, CreativeWork},
+ assertions::{c2pa_action, labels, Action, Actions, CreativeWork},
openssl::temp_signer::get_signer,
Ingredient, Manifest, ManifestStore,
};
diff --git a/sdk/src/assertion.rs b/sdk/src/assertion.rs
@@ -98,10 +98,10 @@ pub fn get_thumbnail_instance(label: &str) -> Option<usize> {
}
}
-/// The core required trait for all assertions
+/// The core required trait for all assertions.
///
/// This defines the label and version for the assertion
-/// and supplies the to/from converters for c2pa assertion format
+/// and supplies the to/from converters for C2PA assertion format.
pub trait AssertionBase
where
Self: Sized,
@@ -110,7 +110,7 @@ where
const VERSION: Option<usize> = None;
- /// Return a label for this assertion (can be overridden )
+ /// Returns a label for this assertion.
fn label(&self) -> &str {
Self::LABEL
}
@@ -202,10 +202,12 @@ impl fmt::Debug for AssertionData {
}
}
-/// Standard Assertion data types. Each assertion type will
-/// contain its AssertionData. For the User Assertion type we
-/// allow a String to set the label. The AssertionData contains
-/// the data payload for the assertion and the version number for its schema (if supported).
+/// Internal Assertion structure
+///
+// Each assertion type will
+// contain its AssertionData. For the User Assertion type we
+// allow a String to set the label. The AssertionData contains
+// the data payload for the assertion and the version number for its schema (if supported).
#[derive(Clone, Debug, PartialEq)]
pub struct Assertion {
label: String,
diff --git a/sdk/src/assertions/data_hash.rs b/sdk/src/assertions/data_hash.rs
@@ -88,10 +88,6 @@ impl DataHash {
self.hash = hash;
}
- pub fn exclusions(&self) -> Option<&Vec<Exclusion>> {
- self.exclusions.as_ref()
- }
-
pub fn add_padding(&mut self, padding: Vec<u8>) {
self.pad = padding;
}
@@ -108,13 +104,6 @@ impl DataHash {
Ok(())
}
- // generate the hash again
- pub fn regen_hash(&mut self) -> Result<()> {
- let p = self.path.clone();
- self.hash = self.hash_from_asset(p.as_path())?;
- Ok(())
- }
-
// add padding to match size
pub fn pad_to_size(&mut self, desired_size: usize) -> Result<()> {
let mut curr_size = self.to_assertion()?.data().len();
diff --git a/sdk/src/assertions/mod.rs b/sdk/src/assertions/mod.rs
@@ -11,17 +11,20 @@
// specific language governing permissions and limitations under
// each license.
+//! Assertion helpers to build, validate, and parse assertions.
+
mod actions;
pub use actions::*;
+#[allow(dead_code)] // will become public later
mod data_hash;
-pub use data_hash::DataHash;
+pub(crate) use data_hash::DataHash;
mod creative_work;
pub use creative_work::CreativeWork;
-
+#[allow(dead_code)] // will become public later
mod ingredient;
-pub use ingredient::{Ingredient, Relationship};
+pub(crate) use ingredient::{Ingredient, Relationship};
pub mod labels;
@@ -32,7 +35,7 @@ mod schema_org;
pub use schema_org::{SchemaDotOrg, SchemaDotOrgPerson};
mod thumbnail;
-pub use thumbnail::Thumbnail;
+pub(crate) use thumbnail::Thumbnail;
mod user;
pub use user::User;
diff --git a/sdk/src/lib.rs b/sdk/src/lib.rs
@@ -19,19 +19,27 @@
//! This library supports reading, creating and embedding C2PA data
//! with JPEG and PNG images.
//!
-//! # Example: Reading and displaying a manifest as JSON
+//! # Example: Reading a `ManifestStore`
//!
//! ```
//! # use c2pa::Result;
-//! use c2pa::ManifestStore;
+//! use c2pa::{assertions::Actions, ManifestStore};
+//!
//! # fn main() -> Result<()> {
//! let manifest_store = ManifestStore::from_file("tests/fixtures/C.jpg")?;
//! println!("{}", manifest_store);
+//!
+//! if let Some(manifest) = manifest_store.get_active() {
+//! let actions: Actions = manifest.find_assertion(Actions::LABEL)?;
+//! for action in actions.actions {
+//! println!("{}\n", action.label);
+//! }
+//! }
//! # Ok(())
//! # }
//! ```
//!
-//! # Example: Adding a manifest to a file
+//! # Example: Adding a `Manifest` to a file
//!
//! ```
//! # use c2pa::Result;
@@ -40,14 +48,18 @@
//! openssl::temp_signer::get_signer,
//! assertions::User
//! };
+//!
//! use std::path::PathBuf;
//! use tempfile::tempdir;
+//!
//! # fn main() -> Result<()> {
//! let mut manifest = Manifest::new("my_app".to_owned());
-//! manifest.add_assertion(&User::new("org.contentauth.mylabel",r#"{"my_tag":"Anything I want"}"#))?;
+//! manifest.add_assertion(&User::new("org.contentauth.mylabel", r#"{"my_tag":"Anything I want"}"#))?;
+//!
//! let source = PathBuf::from("tests/fixtures/C.jpg");
//! let dir = tempdir()?;
//! let dest = dir.path().join("test_file.jpg");
+//!
//! let (signer, _) = get_signer(&dir.path());
//! manifest.embed(&source, &dest, &signer)?;
//! # Ok(())
@@ -58,16 +70,22 @@ pub use assertion::{
Assertion, AssertionBase, AssertionCbor, AssertionDecodeResult, AssertionJson,
};
pub mod assertions;
+
mod cose_validator;
+
mod error;
pub use error::{Error, Result};
+
mod ingredient;
pub use ingredient::{Ingredient, IngredientOptions};
pub mod jumbf_io; // used by make_tests
+
mod manifest;
pub use manifest::{Manifest, ManifestAssertion};
+
mod manifest_store;
pub use manifest_store::ManifestStore;
+
mod manifest_store_report;
pub use manifest_store_report::ManifestStoreReport;
diff --git a/sdk/src/manifest.rs b/sdk/src/manifest.rs
@@ -199,7 +199,7 @@ impl Manifest {
}
/// Retrieves an assertion by label if it exists or Error::NotFound
- pub fn find_assertion<T: DeserializeOwned>(&mut self, label: &str) -> Result<T> {
+ pub fn find_assertion<T: DeserializeOwned>(&self, label: &str) -> Result<T> {
if let Some(manifest_assertion) = self.assertions.iter().find(|a| a.label == label) {
manifest_assertion.to_assertion()
} else {
diff --git a/sdk/src/utils/mod.rs b/sdk/src/utils/mod.rs
@@ -12,6 +12,7 @@
// each license.
pub(crate) mod cbor_types;
+#[allow(dead_code)]
pub(crate) mod hash_utils;
#[allow(dead_code)] // for wasm build
pub(crate) mod patch;
