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.
  • OptionsDeprecated
    Deprecated. Use public_api::Builder instead.
  • 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

Type Definitions