Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
//! Dumps the public API of the cua Rust crates as a small, deterministic JSON
//! document for `scripts/docs-generators/rust-crates.ts`.
//!
//! rustdoc JSON is nightly-only and its format changes between nightlies, so
//! this tool pins one nightly (`rust-toolchain.toml`, [`NIGHTLY`]) together
//! with the `rustdoc-types` release that reads its format, and refuses any
//! other format version.
//!
//! ```text
//! cua-rustdoc-json --workspace libs/cua --target-dir DIR [--out FILE] CRATE...
//! cua-rustdoc-json --from-json DIR [--out FILE] CRATE... # reuse existing JSON
//! ```
use std::collections::{BTreeMap, HashSet};
use std::path::{Path as FsPath, PathBuf};
use std::process::Command;
use rustdoc_types::{
Attribute, Crate, FORMAT_VERSION, FunctionHeader, FunctionSignature, GenericArg, GenericArgs,
GenericBound, GenericParamDef, GenericParamDefKind, Generics, Id, Item, ItemEnum, Path,
PreciseCapturingArg, StructKind, Term, TraitBoundModifier, Type, VariantKind, Visibility,
WherePredicate,
};
use serde::Serialize;
/// The nightly whose rustdoc JSON matches `rustdoc-types` (keep in lockstep
/// with `rust-toolchain.toml` and `Cargo.toml`).
pub const NIGHTLY: &str = "nightly-2026-09-20";
#[derive(Serialize, Debug, PartialEq)]
pub struct Dump {
pub tool: &'static str,
pub toolchain: &'static str,
pub format_version: u32,
pub crates: Vec<CrateDoc>,
}
#[derive(Serialize, Debug, PartialEq)]
pub struct CrateDoc {
pub name: String,
pub lib: String,
pub docs: String,
pub items: Vec<ItemDoc>,
}
#[derive(Serialize, Debug, PartialEq, Default)]
pub struct ItemDoc {
/// `module::path::Name` as a user imports it.
pub path: String,
pub module: String,
pub name: String,
pub kind: String,
/// Source file relative to the crate root (`src/...`), for grouping.
pub source: String,
pub signature: String,
pub docs: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub deprecated: Option<String>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub fields: Vec<Member>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub variants: Vec<Member>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub methods: Vec<Member>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub traits: Vec<String>,
}
#[derive(Serialize, Debug, PartialEq)]
pub struct Member {
pub name: String,
pub signature: String,
pub docs: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub deprecated: Option<String>,
}
/// Trait impls that are binding plumbing, not API (UniFFI converters, etc.).
const HIDDEN_TRAIT_CRATES: &[&str] = &["uniffi", "uniffi_core", "uniffi_macros"];
fn main() {
if let Err(e) = run() {
eprintln!("cua-rustdoc-json: {e}");
std::process::exit(1);
}
}
fn run() -> Result<(), String> {
let mut args = std::env::args().skip(1);
let (mut workspace, mut target, mut from_json, mut out) = (None, None, None, None);
let mut crates = Vec::new();
while let Some(a) = args.next() {
match a.as_str() {
"--workspace" => workspace = args.next().map(PathBuf::from),
"--target-dir" => target = args.next().map(PathBuf::from),
"--from-json" => from_json = args.next().map(PathBuf::from),
"--out" => out = args.next().map(PathBuf::from),
"--print-toolchain" => {
println!("{NIGHTLY}");
return Ok(());
}
s if s.starts_with('-') => return Err(format!("unknown flag {s}")),
_ => crates.push(a),
}
}
if crates.is_empty() {
return Err("no crates given".into());
}
let json_dir = match (from_json, workspace) {
(Some(dir), _) => dir,
(None, Some(ws)) => {
let target = target.ok_or("--target-dir is required with --workspace")?;
for krate in &crates {
rustdoc(&ws, &target, krate)?;
}
target.join("doc")
}
(None, None) => return Err("pass --workspace DIR or --from-json DIR".into()),
};
let mut docs = Vec::new();
for krate in &crates {
let lib = krate.replace('-', "_");
let file = json_dir.join(format!("{lib}.json"));
let text = std::fs::read_to_string(&file)
.map_err(|e| format!("reading {}: {e}", file.display()))?;
docs.push(dump_crate(krate, &text)?);
}
let dump = Dump {
tool: "cua-rustdoc-json",
toolchain: NIGHTLY,
format_version: FORMAT_VERSION,
crates: docs,
};
let text = serde_json::to_string_pretty(&dump).map_err(|e| e.to_string())? + "\n";
match out {
Some(p) => std::fs::write(&p, text).map_err(|e| format!("writing {}: {e}", p.display())),
None => {
print!("{text}");
Ok(())
}
}
}
/// `rustup run NIGHTLY cargo rustdoc -p CRATE --lib -- --output-format json`, with the
/// crate's default features (what a path/git dependency gets).
fn rustdoc(workspace: &FsPath, target: &FsPath, krate: &str) -> Result<(), String> {
// `rustup run` so the pinned nightly wins over the workspace's own
// rust-toolchain.toml (stable) for this call only, even when this tool
// itself runs under `cargo run` (which sets CARGO to a toolchain binary).
let status = Command::new("rustup")
.current_dir(workspace)
.args(["run", NIGHTLY, "cargo"])
.args(["rustdoc", "-q", "-p", krate, "--lib", "--target-dir"])
.arg(target)
.args([
"--",
"-Zunstable-options",
"--output-format",
"json",
"--cap-lints",
"allow",
])
.env_remove("RUSTUP_TOOLCHAIN")
.env_remove("CARGO")
.env_remove("RUSTC")
.env_remove("RUSTDOC")
.status()
.map_err(|e| format!("running cargo rustdoc for {krate}: {e}"))?;
if !status.success() {
return Err(format!("cargo rustdoc -p {krate} failed ({status})"));
}
Ok(())
}
pub fn dump_crate(name: &str, json: &str) -> Result<CrateDoc, String> {
// Check the version before a full parse so a mismatch reads clearly.
#[derive(serde::Deserialize)]
struct Version {
format_version: u32,
}
let v: Version = serde_json::from_str(json).map_err(|e| format!("{name}: {e}"))?;
if v.format_version != FORMAT_VERSION {
return Err(format!(
"{name}: rustdoc JSON format {} but rustdoc-types reads {FORMAT_VERSION}; \
run with the pinned {NIGHTLY} (rust-toolchain.toml) or bump both together",
v.format_version
));
}
let krate: Crate = serde_json::from_str(json).map_err(|e| format!("{name}: {e}"))?;
let root = &krate.index[&krate.root];
let lib = root.name.clone().unwrap_or_else(|| name.replace('-', "_"));
let mut w = Walker {
krate: &krate,
items: Vec::new(),
seen: HashSet::new(),
};
w.module(&krate.root, &lib, 0);
// rustdoc lists glob re-exports last; sort so the dump reads by path.
w.items.sort_by(|a, b| a.path.cmp(&b.path));
Ok(CrateDoc {
name: name.into(),
lib,
docs: docs(root),
items: w.items,
})
}
struct Walker<'a> {
krate: &'a Crate,
items: Vec<ItemDoc>,
seen: HashSet<(String, Id)>,
}
impl Walker<'_> {
fn module(&mut self, id: &Id, path: &str, depth: usize) {
if depth > 16 {
return; // Glob cycles are legal Rust; bound the walk.
}
let Some(ItemEnum::Module(m)) = self.krate.index.get(id).map(|i| &i.inner) else {
return;
};
for child in &m.items {
let Some(item) = self.krate.index.get(child) else {
continue;
};
if !is_public(item) || is_plumbing(item) {
continue;
}
match &item.inner {
ItemEnum::Use(u) => match u.id.as_ref().and_then(|t| self.krate.index.get(t)) {
Some(target) if u.is_glob => {
let target_id = target.id;
self.module(&target_id, path, depth + 1);
}
Some(target) => {
if is_plumbing(target) {
continue;
}
let target = target.clone();
self.item(&target, &u.name, path, depth, Some(item));
}
None => {
// A re-export of another crate's item (or glob).
let key = (path.to_string(), *child);
if self.seen.insert(key) {
let glob = if u.is_glob { "::*" } else { "" };
self.items.push(ItemDoc {
path: format!("{path}::{}", u.name),
module: path.into(),
name: u.name.clone(),
kind: "reexport".into(),
source: source(item),
signature: format!("pub use {}{glob};", u.source),
docs: docs(item),
..Default::default()
});
}
}
},
_ => {
let name = item.name.clone().unwrap_or_default();
let item = item.clone();
self.item(&item, &name, path, depth, None);
}
}
}
}
fn item(&mut self, item: &Item, name: &str, module: &str, depth: usize, via: Option<&Item>) {
if !self.seen.insert((module.to_string(), item.id)) {
return;
}
let path = format!("{module}::{name}");
let k = self.krate;
let mut doc = ItemDoc {
path: path.clone(),
module: module.into(),
name: name.into(),
source: source(item),
docs: via
.map(docs)
.filter(|d| !d.is_empty())
.unwrap_or_else(|| docs(item)),
deprecated: deprecated(item),
..Default::default()
};
match &item.inner {
ItemEnum::Module(_) => {
doc.kind = "module".into();
doc.signature = format!("pub mod {name}");
self.items.push(doc);
self.module(&item.id, &path, depth + 1);
return;
}
ItemEnum::Struct(s) => {
doc.kind = "struct".into();
let g = generics(k, &s.generics);
let wh = where_clause(k, &s.generics);
doc.signature = match &s.kind {
StructKind::Unit => format!("pub struct {name}{g}{wh};"),
StructKind::Tuple(fields) => {
let f: Vec<String> = fields
.iter()
.map(|f| match f.and_then(|f| k.index.get(&f)) {
Some(Item {
inner: ItemEnum::StructField(t),
..
}) => {
format!("pub {}", ty(k, t))
}
_ => "_".into(),
})
.collect();
format!("pub struct {name}{g}({}){wh};", f.join(", "))
}
StructKind::Plain {
fields,
has_stripped_fields,
} => {
doc.fields = members(k, fields);
let body = if doc.fields.is_empty() && *has_stripped_fields {
" { /* private fields */ }"
} else if *has_stripped_fields {
" { /* public fields below, plus private fields */ }"
} else {
" { /* fields below */ }"
};
format!("pub struct {name}{g}{wh}{body}")
}
};
self.impls(&mut doc, &s.impls);
}
ItemEnum::Enum(e) => {
doc.kind = "enum".into();
doc.signature = format!(
"pub enum {name}{}{}",
generics(k, &e.generics),
where_clause(k, &e.generics)
);
doc.variants = e
.variants
.iter()
.filter_map(|v| k.index.get(v))
.filter_map(|v| {
let ItemEnum::Variant(var) = &v.inner else {
return None;
};
let vname = v.name.clone().unwrap_or_default();
let sig = match &var.kind {
VariantKind::Plain => vname.clone(),
VariantKind::Tuple(fs) => format!(
"{vname}({})",
fs.iter()
.map(|f| match f.and_then(|f| k.index.get(&f)) {
Some(Item {
inner: ItemEnum::StructField(t),
..
}) => {
ty(k, t)
}
_ => "_".into(),
})
.collect::<Vec<_>>()
.join(", ")
),
VariantKind::Struct { fields, .. } => format!(
"{vname} {{ {} }}",
members(k, fields)
.iter()
.map(|m| m.signature.clone())
.collect::<Vec<_>>()
.join(", ")
),
};
let sig = match &var.discriminant {
Some(d) => format!("{sig} = {}", d.expr),
None => sig,
};
Some(Member {
name: vname,
signature: sig,
docs: docs(v),
deprecated: deprecated(v),
})
})
.collect();
if e.has_stripped_variants {
doc.signature.push_str(" /* some variants hidden */");
}
self.impls(&mut doc, &e.impls);
}
ItemEnum::Union(u) => {
doc.kind = "union".into();
doc.signature = format!("pub union {name}{}", generics(k, &u.generics));
doc.fields = members(k, &u.fields);
self.impls(&mut doc, &u.impls);
}
ItemEnum::Function(f) => {
doc.kind = "function".into();
doc.signature = fn_sig(k, name, &f.header, &f.generics, &f.sig);
}
ItemEnum::Trait(t) => {
doc.kind = "trait".into();
let bounds = if t.bounds.is_empty() {
String::new()
} else {
format!(": {}", bounds_str(k, &t.bounds))
};
doc.signature = format!(
"pub {}{}trait {name}{}{bounds}{}",
if t.is_unsafe { "unsafe " } else { "" },
if t.is_auto { "auto " } else { "" },
generics(k, &t.generics),
where_clause(k, &t.generics)
);
doc.methods = t
.items
.iter()
.filter_map(|i| k.index.get(i))
.filter_map(|i| assoc_member(k, i))
.collect();
}
ItemEnum::TypeAlias(t) => {
doc.kind = "type".into();
doc.signature = format!(
"pub type {name}{}{} = {};",
generics(k, &t.generics),
where_clause(k, &t.generics),
ty(k, &t.type_)
);
}
ItemEnum::Constant { type_, const_ } => {
doc.kind = "constant".into();
doc.signature = format!("pub const {name}: {} = {};", ty(k, type_), const_.expr);
}
ItemEnum::Static(s) => {
doc.kind = "static".into();
doc.signature = format!(
"pub static {}{name}: {};",
if s.is_mutable { "mut " } else { "" },
ty(k, &s.type_)
);
}
ItemEnum::Macro(_) => {
doc.kind = "macro".into();
doc.signature = format!("macro_rules! {name}");
}
_ => return,
}
self.items.push(doc);
}
fn impls(&self, doc: &mut ItemDoc, impls: &[Id]) {
let k = self.krate;
let mut traits = BTreeMap::new();
for id in impls {
let Some(Item {
inner: ItemEnum::Impl(imp),
..
}) = k.index.get(id)
else {
continue;
};
if imp.is_synthetic || imp.blanket_impl.is_some() {
continue;
}
match &imp.trait_ {
None => {
for m in imp.items.iter().filter_map(|i| k.index.get(i)) {
if is_public(m)
&& let Some(member) = assoc_member(k, m)
{
doc.methods.push(member);
}
}
}
Some(tr) => {
if is_hidden_trait(k, tr) {
continue;
}
let neg = if imp.is_negative { "!" } else { "" };
let name = format!("{neg}{}", path_str(k, tr));
traits.insert(name, ());
}
}
}
doc.traits = traits.into_keys().collect();
}
}
fn is_public(item: &Item) -> bool {
matches!(item.visibility, Visibility::Public | Visibility::Default)
}
/// Generated FFI surface (UniFFI scaffolding, `#[no_mangle]` exports).
fn is_plumbing(item: &Item) -> bool {
let name = item.name.as_deref().unwrap_or("");
name.starts_with("uniffi_")
|| name.starts_with("ffi_")
|| name.starts_with("UniFfi")
|| name.starts_with("UNIFFI_")
|| item
.attrs
.iter()
.any(|a| matches!(a, Attribute::NoMangle | Attribute::ExportName(_)))
}
fn is_hidden_trait(k: &Crate, tr: &Path) -> bool {
let Some(summary) = k.paths.get(&tr.id) else {
return false;
};
let krate = k
.external_crates
.get(&summary.crate_id)
.map(|c| c.name.as_str());
krate.is_some_and(|c| HIDDEN_TRAIT_CRATES.contains(&c))
|| summary
.path
.first()
.is_some_and(|p| HIDDEN_TRAIT_CRATES.contains(&p.as_str()))
}
fn docs(item: &Item) -> String {
item.docs.clone().unwrap_or_default().trim().to_string()
}
fn deprecated(item: &Item) -> Option<String> {
item.deprecation.as_ref().map(|d| {
let mut s = String::from("deprecated");
if let Some(since) = &d.since {
s.push_str(&format!(" since {since}"));
}
if let Some(note) = &d.note {
s.push_str(&format!(": {note}"));
}
s
})
}
/// `src/...` relative to the crate root, never an absolute path.
fn source(item: &Item) -> String {
let Some(span) = &item.span else {
return String::new();
};
let p = span.filename.to_string_lossy().replace('\\', "/");
match p.rfind("/src/") {
Some(i) => p[i + 1..].to_string(),
None if p.starts_with("src/") => p,
None => String::new(),
}
}
fn members(k: &Crate, ids: &[Id]) -> Vec<Member> {
ids.iter()
.filter_map(|f| k.index.get(f))
.filter_map(|f| match &f.inner {
ItemEnum::StructField(t) => {
let name = f.name.clone().unwrap_or_default();
Some(Member {
signature: format!("{name}: {}", ty(k, t)),
name,
docs: docs(f),
deprecated: deprecated(f),
})
}
_ => None,
})
.collect()
}
fn assoc_member(k: &Crate, item: &Item) -> Option<Member> {
let name = item.name.clone()?;
let signature = match &item.inner {
ItemEnum::Function(f) => fn_sig(k, &name, &f.header, &f.generics, &f.sig),
ItemEnum::AssocConst { type_, value, .. } => match value {
Some(v) => format!("const {name}: {} = {v};", ty(k, type_)),
None => format!("const {name}: {};", ty(k, type_)),
},
ItemEnum::AssocType {
generics: g,
bounds,
type_,
..
} => {
let b = if bounds.is_empty() {
String::new()
} else {
format!(": {}", bounds_str(k, bounds))
};
let d = type_
.as_ref()
.map(|t| format!(" = {}", ty(k, t)))
.unwrap_or_default();
format!("type {name}{}{b}{d};", generics(k, g))
}
_ => return None,
};
Some(Member {
name,
signature,
docs: docs(item),
deprecated: deprecated(item),
})
}
pub fn fn_sig(
k: &Crate,
name: &str,
h: &FunctionHeader,
g: &Generics,
sig: &FunctionSignature,
) -> String {
let mut s = String::from("pub ");
if h.is_const {
s.push_str("const ");
}
if h.is_async {
s.push_str("async ");
}
if h.is_unsafe {
s.push_str("unsafe ");
}
s.push_str("fn ");
s.push_str(name);
s.push_str(&generics(k, g));
let args: Vec<String> = sig
.inputs
.iter()
.map(|(n, t)| self_arg(n, t).unwrap_or_else(|| format!("{n}: {}", ty(k, t))))
.collect();
s.push('(');
s.push_str(&args.join(", "));
if sig.is_c_variadic {
s.push_str(", ...");
}
s.push(')');
if let Some(out) = &sig.output {
s.push_str(" -> ");
s.push_str(&ty(k, out));
}
s.push_str(&where_clause(k, g));
s
}
fn self_arg(n: &str, t: &Type) -> Option<String> {
if n != "self" {
return None;
}
Some(match t {
Type::Generic(g) if g == "Self" => "self".into(),
Type::BorrowedRef {
lifetime,
is_mutable,
type_,
} if matches!(&**type_, Type::Generic(g) if g == "Self") => {
format!(
"&{}{}self",
lifetime
.as_ref()
.map(|l| format!("{l} "))
.unwrap_or_default(),
if *is_mutable { "mut " } else { "" }
)
}
_ => return None,
})
}
fn generics(k: &Crate, g: &Generics) -> String {
let params: Vec<String> = g
.params
.iter()
.filter(|p| {
!matches!(
p.kind,
GenericParamDefKind::Type {
is_synthetic: true,
..
}
)
})
.map(|p| param(k, p))
.collect();
if params.is_empty() {
String::new()
} else {
format!("<{}>", params.join(", "))
}
}
fn param(k: &Crate, p: &GenericParamDef) -> String {
match &p.kind {
GenericParamDefKind::Lifetime { outlives } if outlives.is_empty() => p.name.clone(),
GenericParamDefKind::Lifetime { outlives } => {
format!("{}: {}", p.name, outlives.join(" + "))
}
GenericParamDefKind::Type {
bounds, default, ..
} => {
let mut s = p.name.clone();
if !bounds.is_empty() {
s.push_str(": ");
s.push_str(&bounds_str(k, bounds));
}
if let Some(d) = default {
s.push_str(" = ");
s.push_str(&ty(k, d));
}
s
}
GenericParamDefKind::Const { type_, default } => {
let d = default
.as_ref()
.map(|d| format!(" = {d}"))
.unwrap_or_default();
format!("const {}: {}{d}", p.name, ty(k, type_))
}
}
}
fn where_clause(k: &Crate, g: &Generics) -> String {
let preds: Vec<String> = g
.where_predicates
.iter()
.map(|p| match p {
WherePredicate::BoundPredicate {
type_,
bounds,
generic_params,
} => {
let hr = if generic_params.is_empty() {
String::new()
} else {
let ps: Vec<String> = generic_params.iter().map(|p| param(k, p)).collect();
format!("for<{}> ", ps.join(", "))
};
format!("{hr}{}: {}", ty(k, type_), bounds_str(k, bounds))
}
WherePredicate::LifetimePredicate { lifetime, outlives } => {
format!("{lifetime}: {}", outlives.join(" + "))
}
WherePredicate::EqPredicate { lhs, rhs } => {
format!("{} == {}", ty(k, lhs), term(k, rhs))
}
})
.collect();
if preds.is_empty() {
String::new()
} else {
format!(" where {}", preds.join(", "))
}
}
fn bounds_str(k: &Crate, bounds: &[GenericBound]) -> String {
bounds
.iter()
.map(|b| match b {
GenericBound::TraitBound {
trait_,
generic_params,
modifier,
} => {
let hr = if generic_params.is_empty() {
String::new()
} else {
let ps: Vec<String> = generic_params.iter().map(|p| param(k, p)).collect();
format!("for<{}> ", ps.join(", "))
};
let m = match modifier {
TraitBoundModifier::None => "",
TraitBoundModifier::Maybe => "?",
TraitBoundModifier::MaybeConst => "~const ",
};
format!("{hr}{m}{}", path_str(k, trait_))
}
GenericBound::Outlives(l) => l.clone(),
GenericBound::Use(args) => format!(
"use<{}>",
args.iter()
.map(|a| match a {
PreciseCapturingArg::Lifetime(l) => l.clone(),
PreciseCapturingArg::Param(p) => p.clone(),
})
.collect::<Vec<_>>()
.join(", ")
),
})
.collect::<Vec<_>>()
.join(" + ")
}
fn term(k: &Crate, t: &Term) -> String {
match t {
Term::Type(t) => ty(k, t),
Term::Constant(c) => c.expr.clone(),
}
}
fn path_str(k: &Crate, p: &Path) -> String {
// The path as written, trimmed to its last segment for readability.
let base = p.path.rsplit("::").next().unwrap_or(&p.path).to_string();
match p.args.as_deref() {
Some(a) => format!("{base}{}", generic_args(k, a)),
None => base,
}
}
fn generic_args(k: &Crate, a: &GenericArgs) -> String {
match a {
GenericArgs::AngleBracketed { args, constraints } => {
let mut parts: Vec<String> = args
.iter()
.map(|a| match a {
GenericArg::Lifetime(l) => l.clone(),
GenericArg::Type(t) => ty(k, t),
GenericArg::Const(c) => c.expr.clone(),
GenericArg::Infer => "_".into(),
})
.collect();
for c in constraints {
let args = c
.args
.as_deref()
.map(|a| generic_args(k, a))
.unwrap_or_default();
parts.push(match &c.binding {
rustdoc_types::AssocItemConstraintKind::Equality(t) => {
format!("{}{args} = {}", c.name, term(k, t))
}
rustdoc_types::AssocItemConstraintKind::Constraint(b) => {
format!("{}{args}: {}", c.name, bounds_str(k, b))
}
});
}
if parts.is_empty() {
String::new()
} else {
format!("<{}>", parts.join(", "))
}
}
GenericArgs::Parenthesized { inputs, output } => {
let ins: Vec<String> = inputs.iter().map(|t| ty(k, t)).collect();
let out = output
.as_ref()
.map(|o| format!(" -> {}", ty(k, o)))
.unwrap_or_default();
format!("({}){out}", ins.join(", "))
}
GenericArgs::ReturnTypeNotation => "(..)".into(),
}
}
pub fn ty(k: &Crate, t: &Type) -> String {
match t {
Type::ResolvedPath(p) => path_str(k, p),
Type::DynTrait(d) => {
let mut parts: Vec<String> = d
.traits
.iter()
.map(|pt| {
if pt.generic_params.is_empty() {
path_str(k, &pt.trait_)
} else {
let ps: Vec<String> =
pt.generic_params.iter().map(|p| param(k, p)).collect();
format!("for<{}> {}", ps.join(", "), path_str(k, &pt.trait_))
}
})
.collect();
if let Some(l) = &d.lifetime {
parts.push(l.clone());
}
format!("dyn {}", parts.join(" + "))
}
Type::Generic(g) => g.clone(),
Type::Primitive(p) => p.clone(),
Type::FunctionPointer(f) => {
let args: Vec<String> = f.sig.inputs.iter().map(|(_, t)| ty(k, t)).collect();
let out = f
.sig
.output
.as_ref()
.map(|o| format!(" -> {}", ty(k, o)))
.unwrap_or_default();
format!(
"{}fn({}){out}",
if f.header.is_unsafe { "unsafe " } else { "" },
args.join(", ")
)
}
Type::Tuple(ts) if ts.len() == 1 => format!("({},)", ty(k, &ts[0])),
Type::Tuple(ts) => format!(
"({})",
ts.iter().map(|t| ty(k, t)).collect::<Vec<_>>().join(", ")
),
Type::Slice(t) => format!("[{}]", ty(k, t)),
Type::Array { type_, len } => format!("[{}; {len}]", ty(k, type_)),
Type::Pat { type_, .. } => ty(k, type_),
Type::ImplTrait(b) => format!("impl {}", bounds_str(k, b)),
Type::Infer => "_".into(),
Type::RawPointer { is_mutable, type_ } => {
format!(
"*{} {}",
if *is_mutable { "mut" } else { "const" },
ty(k, type_)
)
}
Type::BorrowedRef {
lifetime,
is_mutable,
type_,
} => format!(
"&{}{}{}",
lifetime
.as_ref()
.map(|l| format!("{l} "))
.unwrap_or_default(),
if *is_mutable { "mut " } else { "" },
ty(k, type_)
),
Type::QualifiedPath {
name,
args,
self_type,
trait_,
} => {
let a = args
.as_deref()
.map(|a| generic_args(k, a))
.unwrap_or_default();
match trait_ {
Some(tr) if !tr.path.is_empty() => {
format!("<{} as {}>::{name}{a}", ty(k, self_type), path_str(k, tr))
}
_ => format!("{}::{name}{a}", ty(k, self_type)),
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
const LIB: &str = r#"
//! Demo crate.
mod inner {
/// A handle.
#[derive(Clone, Debug)]
pub struct Handle { /// The id.
pub id: u32, secret: u8 }
impl Handle {
/// Makes one.
pub async fn open(name: &str, tags: Vec<String>) -> Result<Self, Error> { let _ = (name, tags); Ok(Handle { id: 1, secret: 0 }) }
fn hidden(&self) {}
/// Borrow it.
pub fn get<'a>(&'a self) -> &'a u32 { let _ = self.secret; &self.id }
}
/// Errors.
#[derive(Debug)]
pub enum Error { /// Nope.
NotFound(String), Other { code: i32 } }
}
pub use inner::*;
/// Things.
pub mod things {
/// A trait.
pub trait Thing: Send { /// Run.
fn run(&mut self, n: Option<u8>) -> impl Iterator<Item = u8>; }
/// Old name.
#[deprecated(since = "0.2.0", note = "use Handle")]
pub type Old = super::Handle;
}
/// The version.
pub const VERSION: &str = "1";
#[unsafe(no_mangle)]
pub extern "C" fn ffi_demo() {}
"#;
fn demo_json() -> String {
let dir =
std::env::temp_dir().join(format!("cua-rustdoc-json-test-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let src = dir.join("demo.rs");
std::fs::write(&src, LIB).unwrap();
let out = Command::new("rustdoc")
.args([
"--edition",
"2024",
"--crate-type",
"lib",
"-Zunstable-options",
"--output-format",
"json",
"-o",
])
.arg(&dir)
.arg(&src)
.env_remove("RUSTDOC")
.output()
.expect("run rustdoc (the pinned nightly from rust-toolchain.toml)");
assert!(
out.status.success(),
"{}",
String::from_utf8_lossy(&out.stderr)
);
let json = std::fs::read_to_string(dir.join("demo.json")).unwrap();
let _ = std::fs::remove_dir_all(&dir);
json
}
#[test]
fn dumps_public_api_through_glob_reexports() {
let doc = dump_crate("demo", &demo_json()).unwrap();
assert_eq!(doc.docs, "Demo crate.");
let names: Vec<&str> = doc.items.iter().map(|i| i.path.as_str()).collect();
assert_eq!(
names,
[
"demo::Error",
"demo::Handle",
"demo::VERSION",
"demo::things",
"demo::things::Old",
"demo::things::Thing"
]
);
let h = &doc.items[1];
assert_eq!(h.kind, "struct");
assert_eq!(h.docs, "A handle.");
assert_eq!(h.traits, ["Clone", "Debug"]);
assert_eq!(h.fields.len(), 1);
assert_eq!(h.fields[0].signature, "id: u32");
let sigs: Vec<&str> = h.methods.iter().map(|m| m.signature.as_str()).collect();
assert_eq!(
sigs,
[
"pub async fn open(name: &str, tags: Vec<String>) -> Result<Self, Error>",
"pub fn get<'a>(&'a self) -> &'a u32"
]
);
let e = &doc.items[0];
let vs: Vec<&str> = e.variants.iter().map(|v| v.signature.as_str()).collect();
assert_eq!(vs, ["NotFound(String)", "Other { code: i32 }"]);
let t = &doc.items[5];
assert_eq!(t.signature, "pub trait Thing: Send");
assert_eq!(
t.methods[0].signature,
"pub fn run(&mut self, n: Option<u8>) -> impl Iterator<Item = u8>"
);
let old = &doc.items[4];
assert_eq!(old.signature, "pub type Old = Handle;");
assert_eq!(
old.deprecated.as_deref(),
Some("deprecated since 0.2.0: use Handle")
);
assert_eq!(doc.items[2].signature, "pub const VERSION: &str = \"1\";");
assert!(doc.items.iter().all(|i| !i.source.starts_with('/')));
}
#[test]
fn rejects_other_format_versions() {
let err = dump_crate("demo", r#"{"format_version": 1}"#).unwrap_err();
assert!(err.contains(NIGHTLY), "{err}");
}
#[test]
fn pinned_toolchain_matches_rust_toolchain_toml() {
let toml = include_str!("../rust-toolchain.toml");
assert!(
toml.contains(&format!("channel = \"{NIGHTLY}\"")),
"rust-toolchain.toml is out of lockstep"
);
}
}