docs: Edit API docs

sdk/src/builder.rs

@@ -385,10 +385,10 @@ pub struct Builder {
     /// In most cases, you create this from a JSON manifest definition.
     pub definition: ManifestDefinition,
 
-    /// Optional remote URL for the manifest
+    /// Optional remote URL for the manifest.
     pub remote_url: Option<String>,
 
-    /// If true, the manifest store will not be embedded in the asset on sign
+    /// If true, the manifest store will not be embedded in the asset on sign.
     pub no_embed: bool,
 
     /// Base path to search for resources.
@@ -513,13 +513,13 @@ impl Builder {
     /// Sets the [`BuilderIntent`] for this [`Builder`].
     ///
     /// An intent lets the API know what kind of manifest to create.
-    /// Intents are `Create`, `Edit`, or `Update`.
-    /// This allows the API to check that you are doing the right thing.
+    /// and check that you are doing the right thing.
     /// It can also do things for you, like add parent ingredients from the source asset
     /// and automatically add required c2pa.created or c2pa.opened actions.
-    /// Create requires a `DigitalSourceType`. It is used for assets without a parent ingredient.
-    /// Edit requires a parent ingredient and is used for most assets that are being edited.
-    /// Update is a special case with many restrictions but is more compact than Edit.
+    /// Intents are `Create`, `Edit`, or `Update`:
+    /// - `Create` requires a `DigitalSourceType` and is used for assets without a parent ingredient.
+    /// - `Edit` requires a parent ingredient and is used for most assets that are being edited.
+    /// - `Update` is a special case with many restrictions but is more compact than `Edit`.
     /// # Arguments
     /// * `intent` - The [`BuilderIntent`] for this [`Builder`].
     /// # Returns
@@ -607,7 +607,7 @@ impl Builder {
         Ok(self)
     }
 
-    /// Returns a [Vec] of mime types that [c2pa-rs] is able to sign.
+    /// Returns a [Vec] of MIME types that the API is able to sign.
     pub fn supported_mime_types() -> Vec<String> {
         jumbf_io::supported_builder_mime_types()
     }

sdk/src/context.rs

@@ -93,9 +93,9 @@ impl IntoSettings for serde_json::Value {
 ///
 /// Context replaces the global Settings pattern with a more flexible, thread-safe approach.
 /// It encapsulates:
-/// - **Settings**: Configuration options for C2PA operations
-/// - **HTTP Resolvers**: Customizable sync and async HTTP resolvers for fetching remote manifests
-/// - **Signer**: The cryptographic signer used to sign manifests
+/// - **Settings**: Configuration options for C2PA operations.
+/// - **HTTP Resolvers**: Customizable sync and async HTTP resolvers for fetching remote manifests.
+/// - **Signer**: The cryptographic signer used to sign manifests.
 ///
 /// # Creating a Signer
 ///
@@ -128,7 +128,9 @@ impl IntoSettings for serde_json::Value {
 /// 2. **Custom Signer**: Use [`with_signer()`](Context::with_signer) to provide a custom signer
 ///    directly. This is useful for HSMs, remote signing services, or custom signing logic.
 ///
-/// # Usage with Builder and Reader
+/// # Examples
+///
+/// ## Usage with Builder and Reader
 ///
 /// Both [`Builder`](crate::Builder) and [`Reader`](crate::Reader) can be created with a Context:
 ///
@@ -148,8 +150,6 @@ impl IntoSettings for serde_json::Value {
 /// # }
 /// ```
 ///
-/// # Examples
-///
 /// ## Basic usage with default settings
 ///
 /// ```
@@ -167,19 +167,6 @@ impl IntoSettings for serde_json::Value {
 /// # }
 /// ```
 ///
-/// ## Configure with TOML settings
-///
-/// ```
-/// # use c2pa::{Context, Result};
-/// # fn main() -> Result<()> {
-/// let toml = r#"
-///     [verify]
-///     verify_after_sign = true
-/// "#;
-/// let context = Context::new().with_settings(toml)?;
-/// # Ok(())
-/// # }
-/// ```
 pub struct Context {
     settings: Settings,
     sync_resolver: SyncResolverState,

sdk/src/lib.rs

@@ -25,10 +25,14 @@
 //! The library has a Builder/Reader API that focuses on simplicity
 //! and stream support.
 //!
+//! For more information, see [CAI open source SDK - Rust library](https://opensource.contentauthenticity.org/docs/rust-sdk/)
+//!
 //! # Examples
 //!
 //! ## Reading a manifest
 //!
+//! TODO - Update to use Context
+//!
 //! ```
 //! # use c2pa::Result;
 //! use c2pa::{assertions::Actions, Reader};
@@ -49,6 +53,9 @@
 //! ```
 //!
 //! ## Adding a signed manifest to a file
+//!
+//! TODO - Change example to be a more common case - Adding parent with intent, ingredient.
+//!
 //! ```
 //! # use c2pa::Result;
 //! use std::io::Cursor;
@@ -80,33 +87,39 @@
 //! # }
 //! ```
 //!
-//! # WASM
-//!
-//! The only supported HTTP features for WASM (not WASI) are `http_reqwest`. This means WASM
-//! only supports the async API for network requests.
-//!
-//! ## WASI
-//!
-//! The only supported HTTP features for WASI are `http_wasi` and `http_wstd`. The former
-//! enables sync network requests, while the latter enables async network requests.
-//!
 //! # Features
 //!
 //! You can enable any of the following features:
 //!
-//! - **default_http** *(enabled by default)*: Enables default HTTP features for sync and async HTTP resolvers (`http_req`, `http_reqwest`, `http_wasi`, and `http_std`).
-//! - **openssl** *(enabled by default)*: Use the vendored `openssl` implementation for cryptography.
-//! - **rust_native_crypto**: Use Rust native cryptography.
+//! These features are enabled by default:
+//! - **default_http**: Enables default HTTP features for sync and async HTTP resolvers (`http_req`, `http_reqwest`, `http_wasi`, and `http_std`).
+//! - **openssl**: Use the vendored `openssl` implementation for cryptography.
+//!
+//! Other features:
 //! - **add_thumbnails**: Adds the [`image`](https://github.com/image-rs/image) crate to enable auto-generated thumbnails, if possible and enabled in settings.
 //! - **fetch_remote_manifests**: Fetches remote manifests over the network when no embedded manifest is present and that option is enabled in settings.
 //! - **file_io**: Enables APIs that use filesystem I/O.
 //! - **json_schema**: Adds the [`schemars`](https://github.com/GREsau/schemars) crate to derive JSON schemas for JSON-compatible structs.
 //! - **pdf**: Enables basic PDF read support.
+//! - **rust_native_crypto**: Use Rust native cryptography.  
+//! TODO - Confirm behavior with openssl 
+//!
+//! ## HTTP features
+//! TODO - Rationalize the HTTP features
 //! - **http_ureq**: Enables `ureq` for sync HTTP requests.
 //! - **http_reqwest**: Enables `reqwest` for async HTTP requests.
 //! - **http_reqwest_blocking**: Enables the `blocking` feature of `reqwest` for sync HTTP requests.
 //! - **http_wasi**: Enables `wasi` for sync HTTP requests on WASI.
 //! - **http_wstd**: Enables `wstd` for async HTTP requests on WASI.
+//!
+//! ## WASM and WASI
+//!
+//! For WASM the only supported HTTP feature is `http_reqwest`. This means WASM
+//! only supports the async API for network requests.
+//!
+//! For WASI the only supported HTTP features are `http_wasi`, which enables sync network requests, 
+//! and `http_wstd` which enables async network requests.
+//!
 
 /// The internal name of the C2PA SDK.
 pub const NAME: &str = "c2pa-rs";
@@ -115,15 +128,13 @@ pub const NAME: &str = "c2pa-rs";
 pub const VERSION: &str = env!("CARGO_PKG_VERSION");
 
 // Public modules
-/// The assertions module contains the definitions for the assertions that are part of the C2PA specification.
+/// The `assertions` module contains the definitions for the assertions that are part of the C2PA specification.
 pub mod assertions;
 
-pub mod context;
-
-/// The cose_sign module contains the definitions for the COSE signing algorithms.
+/// The `cose_sign` module contains the definitions for the COSE signing algorithms.
 pub mod cose_sign;
 
-/// The create_signer module contains the definitions for the signers that are part of the C2PA specification.
+/// The `create_signer` module contains the definitions for the signers that are part of the C2PA specification.
 pub mod create_signer;
 
 /// Cryptography primitives.
@@ -135,14 +146,14 @@ pub mod crypto;
 pub mod dynamic_assertion;
 
 // TODO: pub it when we expose in high-level API
-/// The http module contains generic traits for configuring sync and async http resolvers.
+/// The `http` module contains generic traits for configuring sync and async HTTP resolvers.
 pub(crate) mod http;
 
 /// The `identity` module provides support for the [CAWG identity assertion](https://cawg.io/identity).
 #[doc(hidden)]
 pub mod identity;
 
-/// The jumbf_io module contains the definitions for the JUMBF data in assets.
+/// The `jumbf_io` module contains the definitions for the JUMBF data in assets.
 pub mod jumbf_io;
 
 /// The settings module provides a way to configure the C2PA SDK.
@@ -152,35 +163,39 @@ pub mod settings;
 #[doc(hidden)]
 pub mod status_tracker;
 
-/// The validation_results module contains the definitions for the validation results that are part of the C2PA specification.
+/// The `validation_results` module contains the definitions for the validation results that are part of the C2PA specification.
 pub mod validation_results;
 
-/// The validation_status module contains the definitions for the validation status that are part of the C2PA specification.
+/// The `validation_status` module contains the definitions for the validation status that are part of the C2PA specification.
 #[doc(hidden)]
 pub mod validation_status;
 
 // Public exports
+#[doc(inline)]
 pub use assertions::DigitalSourceType;
 #[doc(inline)]
 pub use assertions::Relationship;
 pub use builder::{Builder, BuilderIntent, ManifestDefinition};
 pub use callback_signer::{CallbackFunc, CallbackSigner};
 pub use claim_generator_info::ClaimGeneratorInfo;
+#[doc(inline)]
 pub use context::Context;
 pub use crypto::raw_signature::SigningAlg;
 pub use error::{Error, Result};
-#[doc(inline)]
+#[doc(hidden)]
 pub use external_manifest::ManifestPatchCallback;
 pub use hash_utils::{hash_stream_by_alg, HashRange};
 pub use hashed_uri::HashedUri;
 pub use ingredient::Ingredient;
 #[cfg(feature = "file_io")]
+#[doc(hidden)]
 pub use ingredient::{DefaultOptions, IngredientOptions};
 pub use manifest::{Manifest, SignatureInfo};
 pub use manifest_assertion::{ManifestAssertion, ManifestAssertionKind};
 pub use reader::Reader;
 #[doc(inline)]
 pub use resource_store::{ResourceRef, ResourceStore};
+#[doc(inline)]
 pub use settings::Settings;
 pub use signer::{AsyncSigner, BoxedAsyncSigner, BoxedSigner, Signer};
 pub use utils::mime::format_from_path;
@@ -195,6 +210,7 @@ pub(crate) mod builder;
 pub(crate) mod callback_signer;
 pub(crate) mod claim;
 pub(crate) mod claim_generator_info;
+pub(crate) mod context;
 pub(crate) mod cose_validator;
 pub(crate) mod error;
 pub(crate) mod external_manifest;

sdk/src/reader.rs

@@ -169,7 +169,7 @@ impl Reader {
     /// # use std::sync::Arc;
     /// # fn main() -> Result<()> {
     /// // Create a shared Context once
-    /// let ctx = Arc::new(Context::new().with_settings(r#"{"verify": {"verify_after_sign": true}}"#)?);
+    /// let ctx = Context::new().with_settings(Settings::new()).into_shared();
     ///
     /// // Share it across multiple Readers (even across threads!)
     /// let reader1 = Reader::from_shared_context(&ctx);
@@ -186,7 +186,7 @@ impl Reader {
         }
     }
 
-    /// Add manifest store from a stream to the [`Reader`]
+    /// Add manifest store from a stream to the [`Reader`].
     /// # Arguments
     /// * `format` - The format of the stream.  MIME type or extension that maps to a MIME type.
     /// * `stream` - The stream to read from.  Must implement the Read and Seek traits.

sdk/src/settings/mod.rs

@@ -420,6 +420,7 @@ impl Settings {
     #[cfg(feature = "file_io")]
     /// Load thread-local [Settings] from a file.
     /// to be deprecated - use [Settings::with_file] instead
+    #[doc(hidden)]
     pub fn from_file<P: AsRef<Path>>(settings_path: P) -> Result<Self> {
         let ext = settings_path
             .as_ref()
@@ -434,6 +435,7 @@ impl Settings {
     /// Load thread-local [Settings] from string representation of the configuration.
     /// Format of configuration must be supplied (json or toml).
     /// to be deprecated - use [Settings::with_json] or [Settings::with_toml] instead
+    #[doc(hidden)]
     pub fn from_string(settings_str: &str, format: &str) -> Result<Self> {
         let f = match format.to_lowercase().as_str() {
             "json" => FileFormat::Json,
@@ -753,12 +755,14 @@ impl Settings {
     }
 
     /// Serializes the thread-local [Settings] into a toml string.
+    #[doc(hidden)]
     pub fn to_toml() -> Result<String> {
         let settings = get_thread_local_settings();
         Ok(toml::to_string(&settings)?)
     }
 
     /// Serializes the thread-local [Settings] into a pretty (formatted) toml string.
+    #[doc(hidden)]
     pub fn to_pretty_toml() -> Result<String> {
         let settings = get_thread_local_settings();
         Ok(toml::to_string_pretty(&settings)?)

sdk/src/utils/hash_utils.rs

@@ -189,6 +189,7 @@ pub fn hash_asset_by_alg_with_inclusions(
 
     The data is again split into range sets breaking at the exclusion points and now also the markers.
 */
+/// May be used to generate hashes in combination with embeddable APIs.
 pub fn hash_stream_by_alg<R>(
     alg: &str,
     data: &mut R,