Crate public_api

This library gives you the public API of a library crate, in the form of a list of public items in the crate. Public items are items that other crates can use. Diffing is also supported.

If you want a convenient CLI for this library, you should use cargo public-api.

As input to the library, a special output format from cargo doc is used, which goes by the name rustdoc JSON. Currently, only cargo doc from the Nightly toolchain can produce rustdoc JSON for a library. You build rustdoc JSON like this:

cargo +nightly rustdoc --lib -- -Z unstable-options --output-format json

Consider using rustdoc_json instead of invoking the above command yourself.

The main entry point to the library is PublicApi::from_rustdoc_json_str, so please read its documentation.

Examples

The two main use cases are listing the public API and diffing different versions of the same public APIs.

List all public items of a crate (the public API)

use std::error::Error;

use public_api::{Options, PublicApi};

fn main() -> Result<(), Box<dyn Error>> {
    let json_path = rustdoc_json::Builder::default()
        .toolchain("nightly")
        .manifest_path("test-apis/example_api-v0.2.0/Cargo.toml")
        .build()?;

    let public_api = PublicApi::from_rustdoc_json(json_path, Options::default())?;

    for public_item in public_api.items() {
        println!("{public_item}");
    }

    Ok(())
}

Diff two versions of a public API

use std::error::Error;

use public_api::{diff::PublicApiDiff, Options, PublicApi};

fn main() -> Result<(), Box<dyn Error>> {
    let options = Options::default();

    let old_json = rustdoc_json::Builder::default()
        .toolchain("nightly")
        .manifest_path("test-apis/example_api-v0.1.0/Cargo.toml")
        .build()?;
    let old = PublicApi::from_rustdoc_json(old_json, options)?;

    let new_json = rustdoc_json::Builder::default()
        .toolchain("nightly")
        .manifest_path("test-apis/example_api-v0.2.0/Cargo.toml")
        .build()?;
    let new = PublicApi::from_rustdoc_json(new_json, options)?;

    let diff = PublicApiDiff::between(old, new);
    println!("{diff:#?}");

    Ok(())
}

The most comprehensive example code on how to use the library can be found in the thin binary wrapper around the library, see https://github.com/Enselic/cargo-public-api/blob/main/public-api/src/main.rs.

Modules

diff

Contains facilities that allows you diff public APIs between releases and commits. cargo public-api contains additional helpers for that.

tokens

The module tp contain all token handling logic.

Structs

Options

Contains various options that you can pass to PublicApi::from_rustdoc_json.

PublicApi

The public API of a crate

PublicItem

Represent a public item of an analyzed crate, i.e. an item that forms part of the public API of a crate. Implements Display so it can be printed. It also implements Ord, but how items are ordered are not stable yet, and will change in later versions.

Enums

Error

Enumerates all errors that can currently occur within this crate.

Constants

MINIMUM_NIGHTLY_VERSION

This constant defines the minimum version of nightly that is required in order for the rustdoc JSON output to be parsable by this library. Note that this library is implemented with stable Rust. But the rustdoc JSON that this library parses can currently only be produced by nightly.

MINIMUM_RUSTDOC_JSON_VERSIONDeprecated

Deprecated, use MINIMUM_NIGHTLY_VERSION instead.

Type Definitions

Result

Shorthand for std::result::Result<T, public_api::Error>.