api_ops!() { /* proc-macro */ }Expand description
Generate public-API traits, forwarding impls, rustdoc, metadata constants and a Markdown renderer from one operation registry per family.
The registry is the single source of truth: this macro generates method
declarations and forwarding impls only; numerical bodies stay hand-written
in the module named by each layer’s forward key. See
tests/api_ops.rs for a complete working registry and
docs/design/api-grammar/implementation.md section 4 for the design.
§Examples
The grammar (a text block, because a proc-macro crate cannot invoke its
own macro from a doctest):
api_ops! {
family: linalg;
layer concrete {
trait_doc: "...";
trait_def: pub trait LinalgOps: AsView;
impl_def: impl<X: AsView + ?Sized> LinalgOps for X;
method_where: [];
receiver: self; // or `session` + `first_arg: &T;` (`&mut self`),
// or `context` (`&self`, first operand is an argument)
tensor_arg: &impl AsView;
exec: &mut dyn Engine; // optional
dest: Dest; // optional; enables `_into`
result: Result;
types { V = Tensor, R = Tensor } // `S` maps an operand typed `S`
forward: crate::api::concrete;
cfg: feature = "autodiff"; // optional; gates the trait and impl
extra_decls { /* hand-written trait items (exception entries) */ }
extra_impls { /* their impls */ }
}
layer core_eager { describe_only; }
op svd {
summary: "...";
operands: (a); // `name: Type` for typed operands
options: SvdOptions; // `options: none;`: no options type, no `_with`
// optional: `generics: <Y: Bound>;` (method generics) and
// `associated;` (no receiver, `Self: Sized`, e.g. concatenate)
output: Svd<V, R>; // `V`/`R`/... are the layer's `types` keys
dtypes: "...";
layers: [concrete];
into: []; // overwrite | accumulate | scaled; with
// `options: none;` the `_into` form takes no options
layout: "...";
errors: [Validation, NumericalFailure(NonConvergence)];
omissions: [];
example concrete: r#"..."#;
// optional, on a described layer: the canonical compiled signature
// as `api/*.txt` renders it; the registry-conformance check requires it
signature core_eager: "pub fn tenferro_ad::EagerSession<'_>::svd(..) -> ..";
}
exceptions {
E08 {
symbols: ["crate::svd_with_exec"];
scope: "..."; category: "..."; owner_module: "...";
reason: "..."; verification: "..."; exit_condition: "...";
status: retired; // or `retained`
}
}
}