Crate public_api

source ·
Expand description

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 rustdoc +nightly is used, which goes by the name rustdoc JSON. Currently, only the nightly toolchain can build rustdoc JSON.

You use the rustdoc-json library to programmatically build rustdoc JSON. See below for example code. To manually build rustdoc JSON you would typically do something like this:

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

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;

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 = public_api::Builder::from_rustdoc_json(json_path).build()?;

    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;

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

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

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

    Ok(())
}

Modules

  • diff
    Contains facilities that allows you diff public APIs between releases and commits. cargo public-api contains additional helpers for that.
  • tokens
    Contains all token handling logic.

Structs

  • Builder
    Builds PublicApis. See the top level module docs for example code.
  • 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_RUST_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.

Type Aliases