Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
e9bf967
chore(quest): claim quest/m1/ffi-export/docs.md
kixelated Nov 20, 2026
1f7a001
feat(ffi)!: carry rustdoc links, sections, and deprecations into ever…
kixelated Nov 20, 2026
d359d82
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-export/docs
kixelated Nov 20, 2026
6bee4ac
fix(ffi): match AssocConst as a unit variant
kixelated Nov 20, 2026
85dd2f1
fix(ffi): keep callback method docs, escape notes, link TS methods, w…
kixelated Nov 20, 2026
d3f3209
fix(ffi): resolve each TypeScript doc link through its module's names…
kixelated Nov 20, 2026
dd66162
fix(ffi): link a TS callback method through its interface, drop off-t…
kixelated Nov 20, 2026
ab173c3
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-export/docs
kixelated Nov 20, 2026
fdb03be
fix(ffi): answer CodeRabbit's and Pullfrog's findings on doc links an…
kixelated Nov 20, 2026
a4757db
fix(ffi): escape a reference image's destination and title written in…
kixelated Nov 20, 2026
1ff77be
chore(ffi): merge base and reconcile generated binding surfaces
Nov 20, 2026
68ec684
fix(ffi): keep exported names from shadowing each binding's deprecati…
kixelated Nov 20, 2026
547ca05
style(ffi): format
kixelated Nov 20, 2026
3c5d56a
fix(ffi): merge each target's doc links, and keep Swift's stored name…
kixelated Nov 20, 2026
4e42f0c
style(ffi): format
kixelated Nov 20, 2026
b3b0026
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-export/docs
kixelated Nov 20, 2026
564d88d
fix(ffi): link a Python variant by its class's final name
kixelated Nov 20, 2026
0f2eef2
fix(ffi): deprecate in Dart only through @Deprecated, which no member…
kixelated Nov 20, 2026
6d935c1
quest: record the maintainer's follow-up answers
kixelated Nov 20, 2026
c9675ac
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-export/docs
kixelated Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 147 additions & 0 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5110,3 +5110,150 @@ impl Key {
)
}
}

/// A type named as Kotlin's and Dart's deprecation annotation, which the bindings' own
/// annotations must not resolve to.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct Deprecated {
pub on: bool,
/// Named as the Swift record's own conversion, which its stored field must not be.
#[deprecated]
pub lower: u32,
/// Named as Dart's annotation, which its sibling's must not resolve to.
pub deprecated: bool,
}

/// A function named as Dart's deprecation annotation, which the deprecated items after it
/// must not resolve to.
pub fn deprecated(note: u8) -> u8 {
note
}

/// A dial, whose docs carry each rustdoc form a binding renders as its own: links to a
/// method [`Self::turn`], a field [`Dial::level`], a variant [`Error::Overflow`], a
/// function [`advance`], a constant [`LIMIT`], an object [`Counter`], a callback's method
/// [`Log::log`], [`Spawned`], which the web lacks, a method [`clash::Span::width`] and the
/// [field](field@clash::Span::width) of its name, [`Vec`], which no binding has, and
/// [a link with its own text](Self::turn).
///
/// # Examples
///
/// ```
/// let dial = api::Dial::default();
/// assert_eq!(dial.level, 0);
/// ```
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct Dial {
/// How far it is turned, below [`LIMIT`].
pub level: u64,
/// What [`Self::level`] was before the last turn.
#[deprecated(note = "keep the [`Dial`] from before the turn")]
pub before: u64,
}

impl Dial {
/// The dial turned `by` more.
///
/// # Errors
///
/// [`Error::Overflow`] past [`LIMIT`].
///
/// # Panics
///
/// When `by` is zero.
#[allow(deprecated, reason = "it keeps the field it deprecates")]
pub fn turn(self, by: u64) -> Result<Dial, Error> {
assert!(by != 0, "a turn by nothing");
match self.level.checked_add(by) {
Some(level) if level <= LIMIT => Ok(Dial {
level,
before: self.level,
}),
_ => Err(Error::Overflow),
}
}

/// The dial turned all the way: use [`Self::turn`].
#[deprecated(since = "0.2.0", note = "turn it by [`LIMIT`] with [`Dial::turn`]")]
pub fn max(self) -> Dial {
#[allow(deprecated, reason = "it keeps the field it deprecates")]
Dial {
level: LIMIT,
before: self.level,
}
}
}

/// A knob, deprecated as a whole: [`Dial`] replaces it.
#[deprecated(note = "use [`Dial`], whose 'level' is \"the same\" at $0\nand past it")]
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct Knob {
pub level: u64,
}

#[allow(deprecated, reason = "it is the type it deprecates")]
impl Knob {
/// Its level, twice.
pub fn doubled(&self) -> u64 {
self.level * 2
}
}

/// A knob behind a handle, which reaches its deprecated type's methods, deprecated too.
#[allow(deprecated, reason = "it holds the type it deprecates")]
pub struct Holder {
knob: Knob,
}

#[allow(deprecated, reason = "it holds the type it deprecates")]
impl Holder {
/// A knob at `level`.
pub fn new(level: u64) -> Self {
Self { knob: Knob { level } }
}
}

#[allow(deprecated, reason = "it holds the type it deprecates")]
impl std::ops::Deref for Holder {
type Target = Knob;

fn deref(&self) -> &Knob {
&self.knob
}
}

/// The knob of `dial`.
#[deprecated]
#[allow(deprecated, reason = "it returns the type it deprecates")]
pub fn knob(dial: Dial) -> Knob {
Knob { level: dial.level }
}

/// The level of `dial`, from a future.
#[deprecated(note = "read its `level`")]
pub async fn level_later(dial: Dial) -> u64 {
dial.level
}

/// What turns a [`Dial`], implemented in each binding.
pub trait Turner {
/// How far to turn.
fn by(&self) -> u64;

/// How far to turn once.
#[deprecated(note = "turn [`Turner::by`] instead")]
fn once(&self) -> u64;
}

/// `dial` turned as `turner` says, and once more.
#[allow(deprecated, reason = "it calls the method it deprecates")]
pub fn turned(dial: Dial, turner: impl Turner) -> Result<Dial, Error> {
dial.turn(turner.by())?.turn(turner.once())
}

/// The most a [`Dial`] turns, a name the web's globals take too: [`URL`] links its own.
pub const URL: u64 = LIMIT;

/// The step a [`Dial`] turned by before [`Dial::turn`] took any, at most [`URL`].
#[deprecated(note = "pass a step to [`Dial::turn`], whose `}` or `{` alone stays in the note")]
pub const STEP: u64 = 1;
10 changes: 10 additions & 0 deletions ffi/runtime/python.rs
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,16 @@ pub fn raise<T>(exc: *mut PyObject, msg: &str) -> R<T> {
Err(Raised)
}

/// Warn of a call of a deprecated item, as `msg` says: a `DeprecationWarning` at the caller
/// `level` frames up, which raises where warnings are errors.
pub fn deprecated(msg: &CStr, level: isize) -> R<()> {
// SAFETY: the GIL is held, and the category is a static warning type.
match unsafe { PyErr_WarnEx(PyExc_DeprecationWarning, msg.as_ptr(), level) } {
0 => Ok(()),
_ => Err(Raised),
}
}

/// Raise for a call of `what`, or a value of it crossing in, which the library's target
/// lacks: the binding serves other targets, which have it.
pub fn missing<T>(what: &str) -> R<T> {
Expand Down
81 changes: 73 additions & 8 deletions ffi/src/c.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@ pub(crate) fn header(abi: &Abi<'_>, packages: &str) -> (String, u64, BTreeMap<St
};
h.write();
h.name_items();
h.out = crate::doc::links(&h.out, abi.api, |l| match l.text {
Some(_) => None,
None => Some(link(abi, l.target)),
});
// Platform independent, so a header names the same contract wherever it is generated.
let mut hasher = StableHasher::new();
hasher.write(h.out.as_bytes());
Expand Down Expand Up @@ -184,7 +188,7 @@ impl Header<'_> {
.collect();
self.line(format!(
"{}typedef enum {name} {{\n{}\n}} {name};\n",
comment(&e.docs, ""),
comment(&deprecation(&e.docs, e.deprecated.as_deref()), ""),
variants.join("\n")
));
}
Expand Down Expand Up @@ -241,7 +245,7 @@ impl Header<'_> {
let docs = format!(
"{}: implemented in C. Rust calls free once it drops the implementation, and\nmay call the others from any thread.\n\n{}",
callback.path.join("::"),
callback.docs
deprecation(&callback.docs, callback.deprecated.as_deref())
);
self.line(format!(
"{}typedef struct {name}_vtable {{\n{}\n}} {name}_vtable;\n\ntypedef struct {name} {{\n\tconst {name}_vtable *vtable;\n\tvoid *data;\n}} {name};\n",
Expand All @@ -257,7 +261,7 @@ impl Header<'_> {
};
self.line(format!(
"{}#define {} {value}",
comment(&constant.docs, ""),
comment(&deprecation(&constant.docs, constant.deprecated.as_deref()), ""),
abi.constant(&constant.path)
));
}
Expand Down Expand Up @@ -302,7 +306,11 @@ impl Header<'_> {
}
for (i, object) in api.objects.iter().enumerate() {
let name = abi.object(i);
let docs = format!("{}\n\n{}", abi.api.rust(&object.path, &object.args), object.docs);
let docs = format!(
"{}\n\n{}",
abi.api.rust(&object.path, &object.args),
deprecation(&object.docs, object.deprecated.as_deref())
);
self.line(comment(docs.trim(), "").trim_end());
self.line(format!("void {name}_free({name} *self);"));
if abi.checked[i] {
Expand Down Expand Up @@ -421,7 +429,7 @@ impl Header<'_> {
if let Some(opaque) = &record.opaque {
self.line(format!(
"{}typedef struct {name} {{\n\t/* Its bytes, which only Rust reads: copy it, but never make or change one. */\n\t{} opaque[{}];\n}} {name};\n",
comment(&record.docs, ""),
comment(&deprecation(&record.docs, record.deprecated.as_deref()), ""),
c_unit(opaque.unit()),
opaque.units()
));
Expand All @@ -435,11 +443,17 @@ impl Header<'_> {
.fields
.iter()
.zip(&fields)
.map(|(f, ty)| format!("{}\t{};", comment(&f.docs, "\t"), self.decl(ty, &abi::escape(&f.name))))
.map(|(f, ty)| {
format!(
"{}\t{};",
comment(&deprecation(&f.docs, f.deprecated.as_deref()), "\t"),
self.decl(ty, &abi::escape(&f.name))
)
})
.collect();
self.line(format!(
"{}typedef struct {name} {{\n{}\n}} {name};\n",
comment(&record.docs, ""),
comment(&deprecation(&record.docs, record.deprecated.as_deref()), ""),
decls.join("\n")
));
return;
Expand Down Expand Up @@ -517,7 +531,8 @@ impl Header<'_> {
fn function(&mut self, function: &Function, owner: Option<&Ty>) {
let export = self.abi.export(function, owner);
crate::lock::function(&mut self.names, function, &export.call.name);
let mut docs = function.docs.clone();
let sections = crate::doc::sections(&function.docs);
let mut docs = sections.body;
// What the call moves out of the caller's handles, which are then only freed.
// A handle taken by value: one taken `&mut` is not `const` either, but stays.
let receiver = function.receiver.map(|r| r == Receiver::Owned);
Expand Down Expand Up @@ -592,6 +607,13 @@ impl Header<'_> {
api.named(function.on).join(", ")
));
}
if let Some(errors) = &sections.errors {
docs.push_str(&format!("\n\n# Errors\n\n{errors}"));
}
if let Some(panics) = &sections.panics {
docs.push_str(&format!("\n\n# Aborts\n\n{panics}"));
}
let docs = deprecation(&docs, function.deprecated.as_deref());
self.out.push_str(&comment(docs.trim(), ""));
if let Some(future) = &export.future {
let handle = &future.handle;
Expand Down Expand Up @@ -660,6 +682,49 @@ pub(crate) fn decl(abi: &Abi<'_>, ty: &Ty, name: &str) -> String {
}
}

/// `docs`, then the note of `deprecated`, where it has one: C's compilers would warn of the
/// C++ header's own calls, so the header only says so.
fn deprecation(docs: &str, deprecated: Option<&str>) -> String {
match deprecated {
Some("") => format!("{docs}\n\nDeprecated."),
Some(note) => format!("{docs}\n\nDeprecated: {note}"),
None => docs.to_string(),
}
.trim()
.to_string()
}

/// The C name a link in the header's comments names for `target`.
fn link(abi: &Abi<'_>, target: crate::doc::Target<'_>) -> String {
use crate::doc::{Owner, Target};
let api = abi.api;
let owner = |owner: Owner| match owner {
Owner::Record(i) => Ty::Struct(abi.record(i)),
Owner::Enum(i) => abi.ty(&Type::Enum(i)),
Owner::Object(i) => Ty::Handle {
name: abi.object(i),
constant: false,
},
Owner::Callback(i) => Ty::Struct(abi.callback(i)),
};
match target {
Target::Record(i) => abi.record(i),
Target::Enum(i) => abi.enumeration(i),
Target::Object(i) => abi.object(i),
Target::Callback(i) => abi.callback(i),
Target::Variant(i, v) => format!(
"{}_{}",
abi.enumeration(i).to_uppercase(),
abi::snake(&api.enums[i].variants[v].name).to_uppercase()
),
Target::Field(i, n) => format!("{}.{}", abi.record(i), abi::escape(&api.records[i].fields[n].name)),
Target::Constant(c) => abi.constant(&c.path),
// A callback's method is its table's member.
Target::Function(Some(Owner::Callback(i)), f) => format!("{}_vtable.{}", abi.callback(i), f.name()),
Target::Function(of, f) => format!("{}()", abi.export(f, of.map(owner).as_ref()).call.name),
}
}

/// A C comment holding `docs`, each line indented by `indent`, or nothing for none.
fn comment(docs: &str, indent: &str) -> String {
if docs.is_empty() {
Expand Down
Loading