Skip to content

docs: Edit and cleanup pass #249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
crandmck wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs: Edit and cleanup pass #249

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a65b0b9
docs: use github-only CSS class instead of inline display:none style
crandmck Jul 23, 2026
db5b835
Copy edit
crandmck Jul 24, 2026
2f7c9e7
Remove Rust-specific stuff from CONTRIBUTING.md
crandmck Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,9 @@ by project committers. Read [GitHub's pull request documentation](https://help.g
for more information on sending pull requests.

Code submissions will need to pass all automated tests in place at the time of submission.
These include such things as Rust code format, Clippy/lint checks, and unit test coverage.
These include such things as code format, lint checks, and unit test coverage.

We encourage you to raise an issue in GitHub before starting work on a major addition to the crate.
We encourage you to raise an issue in GitHub before starting work on a major addition to the library.
This will give us an opportunity to discuss API design and avoid duplicate efforts.

### Pull request titles
Expand Down
19 changes: 9 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,19 @@ The [c2pa-cpp repository](https://github.com/contentauth/c2pa-cpp) implements C+
Although this library works for plain C applications, the documentation assumes you're using C++, since that's most common for modern applications.

<div class="hide-doxygen" >
<div style={{display: 'none'}}>
<div class="github-only">

For the best experience, read the docs on the [CAI Open Source SDK documentation website](https://opensource.contentauthenticity.org/docs/c2pa-c).
For the best experience, read the docs on the [CAI Open Source SDK documentation website](https://opensource.contentauthenticity.org/docs/c2pa-cpp).

If you want to view the documentation in GitHub, see:
- [Using the C++ library](docs/usage.md)
- [Supported formats](https://github.com/contentauth/c2pa-rs/blob/main/docs/supported-formats.md)
- [Configuring the SDK using `Context` and `Settings`](docs/context-settings.md)
- [Using Builder intents](docs/intents.md) to ensure spec-compliant manifests
- Using [working stores and archvies](docs/working-stores.md)
- Using [working stores and archives](docs/working-stores.md)
- Selectively constructing manifests by [filtering actions and ingredients](docs/selective-manifests.md)
- Using the [embeddable API for low-level control over embedding manifests](docs/embeddable-api.md)
- [Frequently-asked questions (FAQs)](docs/faqs.md)
- [Frequently asked questions (FAQs)](docs/faqs.md)
- [Release notes](docs/release-notes.md)

</div>
Expand All @@ -45,7 +45,7 @@ target_link_libraries(myapp PRIVATE c2pa_cpp)

This will automatically fetch, build, and link the `c2pa_cpp` library and its dependencies.

> **Note:**
> [!NOTE]
> This project uses pre-built dynamic libraries from the [c2pa-rs](https://github.com/contentauth/c2pa-rs) repository. It should select the correct library for your platform. If your platform is not supported, you can build your own library using the c2pa_rs repo.

### Example usage
Expand All @@ -68,7 +68,7 @@ Enter this command to build the SDK:
make release
```

This will download the [pre-build libraries published with c2pa releases](https://github.com/contentauth/c2pa-rs/releases), build and link the C++ code.
This will download the [prebuilt libraries published with c2pa releases](https://github.com/contentauth/c2pa-rs/releases), build and link the C++ code.

The Makefile has a number of other targets; for example:
- `test` to run unit tests
Expand All @@ -80,7 +80,7 @@ Results are saved in the `build` directory.

### Building using local sources

This project can also be built entirely from source (without pre-built library download), with the pre-requisite that you will also need [c2pa-rs](https://github.com/contentauth/c2pa-rs) on the local machine, as well as the [Rust toolchain](https://rust-lang.org/tools/install/).
This project can also be built entirely from source (without pre-built library download), with the prerequisite that you will also need [c2pa-rs](https://github.com/contentauth/c2pa-rs) on the local machine, as well as the [Rust toolchain](https://rust-lang.org/tools/install/).

To build in this case, the build scripts need to be able to locate the `c2pa-rs` sources as well as the library this builds for linking. This is done by setting environment variables in the terminal where the builds will run.

Expand Down Expand Up @@ -145,7 +145,7 @@ AddressSanitizer: CHECK failed: sanitizer_malloc_mac.inc:189 "((!asan_init_is_ru
This is an incompatibility between an older AppleClang sanitizer runtime and the host
malloc. The fix is to build the sanitizer target with a newer LLVM/Clang (for example, Homebrew's `llvm`).

To do so, install (or update) an `llvm` version. For instance, using homebrew::
To do so, install (or update) an `llvm` version. For instance, using homebrew:

```sh
brew install llvm
Expand Down Expand Up @@ -173,10 +173,9 @@ And finally run the test executable:
ctest --test-dir build/debug --output-on-failure
```


### Building API documentation

API documentation generated by Doxygen is automatically built on each PR.
Doxygen automatically builds API documentation on each PR.

To generate API docs locally, these are the main files:

Expand Down
26 changes: 13 additions & 13 deletions docs/context-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,12 +61,12 @@ c2pa::Reader reader(context, "image.jpg");

> [!NOTE]
> The deprecated `c2pa::load_settings(data, format)` still works but you should migrate to `Context`. **Never mix the two approaches**.
> See [Migrating from deprecated APIS](#migrating-from-deprecated-apis).
> See [Migrating from deprecated APIs](#migrating-from-deprecated-apis).

### Context lifecycle

- **Non-copyable, moveable**: `Context` can be moved but not copied. After moving, `is_valid()` returns `false` on the source
- **Pass as `shared_ptr`**: `Reader` and `Builder` retain a shared reference to the context, keeping it alive for their lifetime. This is required when using progress callbacks — without it, the callback can fire after the context is destroyed, causing a crash
- **Pass as `shared_ptr`**: `Reader` and `Builder` retain a shared reference to the context, keeping it alive for their lifetime. This is required when using progress callbacks: without it, the callback can fire after the context is destroyed, causing a crash
- **Reusable**: Use the same `shared_ptr<Context>` to create multiple readers and builders

```cpp
Expand Down Expand Up @@ -199,10 +199,10 @@ The callback signature is:
bool callback(c2pa::ProgressPhase phase, uint32_t step, uint32_t total);
```

- **`phase`** — which stage the SDK is in (see [`ProgressPhase` values](#progressphase-values) below).
- **`step`** — monotonically increasing counter within the current phase, starting at `1`. Resets to `1` at the start of each new phase. Use as a liveness signal: a rising `step` means the SDK is making forward progress.
- **`total`** — `0` = indeterminate (show a spinner); `1` = single-shot phase; `> 1` = determinate (`step / total` gives a completion fraction).
- **Return value** — return `true` to continue, `false` to request cancellation (same effect as calling `context.cancel()`).
- **`phase`**: which stage the SDK is in (see [ProgressPhase values](#progressphase-values) below).
- **`step`**: monotonically increasing counter within the current phase, starting at `1`. Resets to `1` at the start of each new phase. Use as a liveness signal: a rising `step` means the SDK is making forward progress.
- **`total`**: `0` = indeterminate (show a spinner); `1` = single-shot phase; `> 1` = determinate (`step / total` gives a completion fraction).
- **Return value**: return `true` to continue, `false` to request cancellation (same effect as calling `context.cancel()`).

**Do not throw** from the progress callback. Exceptions cannot cross the C/Rust boundary safely; if your callback throws, the wrapper catches it and the operation is aborted as a cancellation (you do not get your exception back at the call site). Use `return false`, `context.cancel()`, or application-side state instead.

Expand Down Expand Up @@ -238,9 +238,9 @@ try {
cancel_thread.join();
```

`cancel()` is safe to call when no operation is in progress — it is a no-op in that case (and a no-op if the `Context` is moved-from).
`cancel()` is safe to call when no operation is in progress: it is a no-op in that case (and a no-op if the `Context` is moved-from).

### `ProgressPhase` values
### ProgressPhase values

| Phase | When emitted |
|-------|-------------|
Expand Down Expand Up @@ -509,7 +509,7 @@ The [`trust` properties](https://opensource.contentauthenticity.org/docs/manifes
| `trust.trust_anchors` | Default trust anchor root certificates (PEM format). **Replaces** the SDK's built-in trust anchors entirely. | — |
| `trust.trust_config` | Allowed Extended Key Usage (EKU) OIDs for certificate purposes (e.g., document signing: `1.3.6.1.4.1.311.76.59.1.9`). | — |

#### Using `user_anchors`
#### Using user_anchors

For development, add your test root CA without replacing the SDK's default trust store:

Expand All @@ -529,7 +529,7 @@ auto context = std::make_shared<c2pa::Context>(R"({
c2pa::Reader reader(context, "signed_asset.jpg");
```

#### Using `allowed_list`
#### Using allowed_list

For quick testing, bypass chain validation by explicitly allowing a specific certificate:

Expand Down Expand Up @@ -690,9 +690,9 @@ The [`builder` settings](https://opensource.contentauthenticity.org/docs/manifes
#### Builder intent

Use the [`builder.intent` setting](https://opensource.contentauthenticity.org/docs/manifest/json-ref/settings-schema/#builderintent) to specify the purpose of the claim, one of:
- `{"Create": <TYPE>}`: Specifies a new digital creation, where `<TYPE>` is one of the [DigitalSourceType](https://opensource.contentauthenticity.org/docs/manifest/json-ref/settings-schema/#digitalsourcetype).
- `{"Create": <TYPE>}`: Specifies a new digital creation, where `<TYPE>` is one of the [DigitalSourceType](https://opensource.contentauthenticity.org/docs/manifest/json-ref/settings-schema/#digitalsourcetype).
- `{"Edit": null}`: An edit of a pre-existing parent asset.
- `{"Update": null}`: An restricted version of `Edit` type for non-editorial changes.
- `{"Update": null}`: A restricted version of the `Edit` type for non-editorial changes.

> [!TIP]
> For more information on intents, see [Intents](https://opensource.contentauthenticity.org/docs/rust-sdk/docs/intents) and [BuilderIntent in the SDK object reference.](https://opensource.contentauthenticity.org/docs/manifest/json-ref/settings-schema/#builderintent).
Expand Down Expand Up @@ -974,7 +974,7 @@ c2pa::Builder builder(context, manifest_json);
c2pa::Reader::from_asset(context, "image.jpg");
```

The `shared_ptr` overloads accept any `shared_ptr<IContextProvider>`, so custom `IContextProvider` implementations work the same way, wrap them in a `shared_ptr` before passing.
The `shared_ptr` overloads accept any `shared_ptr<IContextProvider>`, so custom `IContextProvider` implementations work the same way: wrap them in a `shared_ptr` before passing.

#### About IContextProvider

Expand Down
Loading