docs: document features in Rust docs and clarify features (#1491)

* docs: document features in lib.rs and clarify features

* fix: remove `serialize_thumbnails` feature docs

* docs: clarify feature language

* docs: clarify removed serialize_thumbnails feature

* Copy edits

* docs: move back feature docs before merge overwrite

* docs: clarify language

---------

Co-authored-by: Rand McKinney <[email protected]>

Author: ok-nick

docs/usage.md

@@ -32,22 +32,26 @@ c2pa = { version = "0.45.2", features = ["file_io", "add_thumbnails"] }
 
 ## Features
 
-The Rust library crate provides the following capabilities:
+You can enable any of the following features:
 
-* `openssl` *(enabled by default)* - Enables the system `openssl` implementation for cryptography.
-* `rust_native_crypto` - Enables the Rust native implementation for cryptography.
-* `add_thumbnails` generates thumbnails automatically for JPEG and PNG files. (no longer included with `file_io`)
-* `fetch_remote_manifests` enables the verification step to retrieve externally referenced manifest stores.  External manifests are only fetched if there is no embedded manifest store and no locally adjacent .c2pa manifest store file of the same name.
-* `file_io` enables manifest generation, signing via OpenSSL, and embedding manifests in [supported file formats](supported-formats.md).
-* `json_schema` is used by `make schema` to produce a JSON schema document that represents the `ManifestStore` data structures.
-* `pdf` - Enable support for reading claims on PDF files.
+- **openssl** *(enabled by default)*: Use the vendored `openssl` implementation for cryptography.
+- **rust_native_crypto**: Use Rust native cryptography.
+- **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.
 
-* the `v1_api` feature is no longer supported.
+> [!NOTE]
+> If both `rust_native_crypto` and `openssl` are enabled, then only `rust_native_crypto` will be enabled.
+> To avoid including `openssl` as a dependency, disable default features when using `rust_native_crypto`.
 
-[!NOTE]
-If both `rust_native_crypto` and `openssl` are enabled, it will default to `rust_native_crypto`.
-It is recommended to disable default features when using `rust_native_crypto` as to avoid including `openssl` as a dependency.
+### Features no longer supported
 
+The following features are no longer supported:
+
+* **v1_api**. The old API that this enabled has been removed.
+* **serialize_thumbnails**. Thumbnails can be serialized by accessing resources directly.
 
 ### Resource references
 
@@ -60,19 +64,20 @@ When defining a resource for the [ManifestStoreBuilder](https://docs.rs/c2pa/lat
 The specification often requires adding a `HashedUri` to an assertion. Since the JUMBF URIs for a new manifest are not known when defining the manifest, this creates a "chicken and egg" scenario, resolved with local resource references. When constructing the JUMBF for a manifest, the library converts all local URI references into JUMBF references and corrects the the associated cross references.
 
 URI schemes in a resource reference can have the following forms:
+
 - `self#jumbf` - An internal JUMBF reference
 - `file:///` - A local file reference
 - `app://contentauth/` - A working store reference
 - `http://` - Remote URI
 - `https://` - Remote secure URI
 
-Note that the `file:` and `app:` schemes are only used in the context of ManifestStoreBuilder and will never be in JUMBF data. This is proposal, currently there is no implementation for file or app schemes and we do not yet handle http/https schemes this way.
+Note that the `file:` and `app:` schemes are only used in the context of `ManifestStoreBuilder` and will never be in JUMBF data. This is proposal, currently there is no implementation for file or app schemes and we do not yet handle HTTP/HTTPS schemes this way.
 
 <!-- Is the above still true? "This is proposal, currently there is no implementation" -->
 
 When `file_io` is enabled, the lack of a scheme will be interpreted as a `file:///` reference, otherwise as an `app:` reference.
 
-### Source asset vs parent asset
+### Source asset versus parent asset
 
 The source asset isn't always the parent asset: The source asset is the asset that is hashed and signed. It can be the output from an editing application that has not preserved the manifest store from the parent. In that case, the application should have extracted a parent ingredient from the parent asset and added that to the manifest definition.
 
@@ -86,6 +91,7 @@ If there is no parent ingredient defined, and the source has a manifest store, t
 ### Remote URLs and embedding
 
 The default operation of C2PA signing is to embed a C2PA manifest store into an asset. The library also returns the C2PA manifest store so that it can be written to a sidecar or uploaded to a remote service.
+
 - The API supports embedding a remote URL reference into the asset.
 - The remote URL is stored in different ways depending on the asset, but is often stored in XMP data.
 - The remote URL must be added to the asset before signing so that it can be hashed along with the asset.
@@ -95,7 +101,6 @@ The default operation of C2PA signing is to embed a C2PA manifest store into an
 - The remote URL can be set with `builder.remote_url`.
 - If embedding is not needed, set the `builder.no_embed` flag to `true`.
 
-
 ## Example code
 
 The [sdk/examples](https://github.com/contentauth/c2pa-rs/tree/main/sdk/examples) directory contains some minimal example code.  The [client/client.rs](https://github.com/contentauth/c2pa-rs/blob/main/sdk/examples/client/client.rs) is the most instructive and provides and example of reading the contents of a manifest store, recursively displaying nested manifests.

sdk/src/lib.rs

@@ -25,7 +25,9 @@
 //! The library has a Builder/Reader API that focuses on simplicity
 //! and stream support.
 //!
-//! ## Example: Reading a ManifestStore
+//! # Examples
+//!
+//! ## Reading a manifest
 //!
 //! ```
 //! # use c2pa::Result;
@@ -46,7 +48,7 @@
 //! # }
 //! ```
 //!
-//! ## Example: Adding a Manifest to a file
+//! ## Adding a manifest to a file
 //!
 //! ```ignore-wasm32
 //! # use c2pa::Result;
@@ -86,6 +88,18 @@
 //! # Ok(())
 //! # }
 //! ```
+//!
+//! # Features
+//!
+//! You can enable any of the following features:
+//!
+//! - **openssl** *(enabled by default)*: Use the vendored `openssl` implementation for cryptography.
+//! - **rust_native_crypto**: Use Rust native cryptography.
+//! - **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.
 
 /// The internal name of the C2PA SDK
 pub const NAME: &str = "c2pa-rs";