Struct public_api::PublicApi

#[non_exhaustive]
pub struct PublicApi { /* private fields */ }

The public API of a crate

Create an instance with PublicApi::from_rustdoc_json().

Rendering the items

To render the items in the public API you can iterate over the items.

You get the rustdoc_json_str in the example below as explained in the crate documentation, either via rustdoc_json or by calling cargo rustdoc yourself.

use public_api::{PublicApi, Options};

let options = Options::default();
// Gather the rustdoc content as described in this crates top-level documentation.
let public_api = PublicApi::from_rustdoc_json_str(&rustdoc_json_str, options)?;

for public_item in public_api.items() {
    // here we print the items to stdout, we could also write to a string or a file.
    println!("{}", public_item);
}

Implementations

impl PublicApi

pub fn from_rustdoc_json(
    path: impl AsRef<Path>,
    options: Options
) -> Result<PublicApi>

Takes a Path to a rustdoc JSON file and returns a PublicApi with PublicItems where each PublicItem is one public item of the crate, i.e. part of the crate’s public API. Use Self::items() or [Self::into_items() to get the items.

There exists a convenient cargo public-api subcommand wrapper for this function found at https://github.com/Enselic/cargo-public-api that builds the rustdoc JSON for you and then invokes this function. If you don’t want to use that wrapper, use rustdoc_json to build and return the path to the rustdoc json or call

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

to generate the rustdoc JSON that this function takes as input. The output is put in ./target/doc/your_library.json. As mentioned, rustdoc_json does this for you.

For reference, the rustdoc JSON format is documented at https://rust-lang.github.io/rfcs/2963-rustdoc-json.html. But the format is still a moving target. Open PRs and issues for rustdoc JSON itself can be found at https://github.com/rust-lang/rust/labels/A-rustdoc-json.

Errors

E.g. if the JSON is invalid or if the file can’t be read.

pub fn from_rustdoc_json_str(
    rustdoc_json_str: impl AsRef<str>,
    options: Options
) -> Result<PublicApi>

Same as Self::from_rustdoc_json, but the rustdoc JSON is read from a &str rather than a file.

Errors

E.g. if the JSON is invalid.

pub fn items(&self) -> impl Iterator<Item = &PublicItem>

Returns an iterator over all public items in the public API

pub fn into_items(self) -> impl Iterator<Item = PublicItem>

Like Self::items(), but ownership of all PublicItems are transferred to the caller.

pub fn missing_item_ids(&self) -> impl Iterator<Item = &String>

The rustdoc JSON IDs of missing but referenced items. Intended for use with --verbose flags or similar.

In some cases, a public item might be referenced from another public item (e.g. a mod), but is missing from the rustdoc JSON file. This occurs for example in the case of re-exports of external modules (see https://github.com/Enselic/cargo-public-api/issues/103). The entries in this Vec are what IDs that could not be found.

The exact format of IDs are to be considered an implementation detail and must not be be relied on.

Trait Implementations

impl Debug for PublicApi

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.