Crate public_api

This library gives you a 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

The main entry point to the library is public_api_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, fs::read_to_string};

use public_api::{public_api_from_rustdoc_json_str, Options};

fn main() -> Result<(), Box<dyn Error>> {
    let public_api = public_api_from_rustdoc_json_str(
        &read_to_string("./tests/rustdoc-json/example_api-v0.2.0.json")?,
        Options::default(),
    )?;

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

    Ok(())
}

Diff two versions of a public API

use std::{error::Error, fs::read_to_string};

use public_api::{diff::PublicItemsDiff, public_api_from_rustdoc_json_str, Options};

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

    let old = public_api_from_rustdoc_json_str(
        &read_to_string("./tests/rustdoc-json/example_api-v0.1.0.json")?,
        options,
    )?;

    let new = public_api_from_rustdoc_json_str(
        &read_to_string("./tests/rustdoc-json/example_api-v0.2.0.json")?,
        options,
    )?;

    let diff = PublicItemsDiff::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 public_api_from_rustdoc_json_str.

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_RUSTDOC_JSON_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.

Functions

public_api_from_rustdoc_json_str

Takes rustdoc JSON and returns a Vec of PublicItems where each PublicItem is one public item of the crate, i.e. part of the crate’s public API.

Type Definitions

Result

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