public-api

List and diff the public API of Rust library crates by analyzing rustdoc JSON output files from the nightly toolchain.

This library is the backbone of cargo public-api.

Usage

The library comes with a thin bin wrapper that can be used to explore the capabilities of this library.

```bash

Build and install the thin bin wrapper with a recent stable Rust toolchain

cargo install public-api

Install nightly-2022-05-19 or later so you can build up-to-date rustdoc JSON files

rustup install nightly ```

List the public API

To list all items that form the public API of your Rust library:

```bash

Generate rustdoc JSON for your own Rust library

% cd ~/src/your_library % RUSTDOCFLAGS='-Z unstable-options --output-format json' cargo +nightly doc --lib --no-deps

List all items in the public API of your Rust library

% public-api ./target/doc/yourlibrary.json pub mod publicapi pub fn publicapi::Options::clone(&self) -> Options pub fn publicapi::Options::default() -> Self pub fn publicapi::PublicItem::clone(&self) -> PublicItem pub fn publicapi::publicapifromrustdocjsonstr(rustdocjsonstr: &str, options: Options) -> Result> pub struct publicapi::Options pub struct publicapi::PublicItem pub struct field publicapi::Options::sorted: bool pub struct field publicapi::Options::withblanket_implementations: bool ... ```

Diff the public API

It is frequently of interest to know how the public API of a crate has changed. You can find this out by doing a diff between different versions of the same library. The higher level tool cargo public-api makes this more convenient, but it is possible without it.

```bash

Generate two different rustdoc JSON files for two different versions of your library

and then pass both files to the bin to make it print the public API diff

% public-api ./target/doc/yourlibrary.old.json ./target/doc/yourlibrary.json Removed: (nothing)

Changed: -pub fn publicapi::sortedpublicapifromrustdocjsonstr(rustdocjsonstr: &str) -> Result> +pub fn publicapi::sortedpublicapifromrustdocjsonstr(rustdocjsonstr: &str, options: Options) -> Result>

Added: +pub fn publicapi::Options::clone(&self) -> Options +pub fn publicapi::Options::default() -> Self +pub struct publicapi::Options +pub struct field publicapi::Options::withblanketimplementations: bool ```

Library documentation

Documentation can be found at docs.rs as usual. There are also some simple examples on how to use the library. The code for the thin bin wrapper might also be of interest.

Historical note

The code for this library used to live at https://github.com/Enselic/public-api. So git tags for old versions are found in that repo rather than this repo.