Crate public_api
source · [−]Expand description
This library gives you a list of all public items (otherwise known as the
public API) of a library crate. 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:
RUSTDOCFLAGS='-Z unstable-options --output-format json' cargo +nightly doc --lib --no-deps
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 public items, and diffing public items.
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/public_api-v0.4.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/public_api-v0.2.0.json")?,
options,
)?;
let new = public_api_from_rustdoc_json_str(
&read_to_string("./tests/rustdoc_json/public_api-v0.4.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/public_api/blob/main/src/main.rs.
Modules
Contains facilities that allows you diff public APIs between releases and
commits. cargo public-api
contains
additional helpers for that.
Structs
Contains various options that you can pass to public_api_from_rustdoc_json_str
.
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
Enumerates all errors that can currently occur within this crate.
Constants
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
Takes rustdoc JSON and returns a Vec
of PublicItem
s where each
PublicItem
is one public item of the crate, i.e. part of the crate’s
public API.
Type Definitions
Shorthand for std::result::Result<T, public_api::Error>
.