buck2 icon indicating copy to clipboard operation
buck2 copied to clipboard

docs generator/starlark derive macros: get docs from `starlark_value` docstring if there's no methods defined

Open lf- opened this issue 5 months ago • 0 comments

#[starlark_value(type = "DynamicAction")]
impl<'v> StarlarkValue<'v> for StarlarkDynamicActions<'v> {
    // Used to add type documentation to the generated documentation
    fn get_methods() -> Option<&'static Methods> {
        static RES: MethodsStatic = MethodsStatic::new();
        RES.methods(dynamic_actions_methods)
    }
}

impl<'v> AllocValue<'v> for StarlarkDynamicActions<'v> {
    fn alloc_value(self, heap: &'v Heap) -> Value<'v> {
        // No need to freeze: we unpack contents of this struct
        // in `ctx.actions.dynamic_output` call.
        heap.alloc_complex_no_freeze(self)
    }
}

/// Opaque thunk type returned from calling the returned value of a `dynamic_actions` or
/// `bxl.dynamic_actions` rule invocation.
///
/// Can be passed to
/// [`AnalysisActions.dynamic_output_new`](../AnalysisActions#analysisactionsdynamic_output_new) to
/// extract its contents.
///
/// Be aware that the context argument of the called impl function differs between
/// [`dynamic_actions`](../#dynamic_actions) where it is [`actions: AnalysisActions`](../AnalysisActions)
/// and [`bxl.dynamic_actions`](../../bxl/#dynamic_actions)
/// where it is [`bxl_ctx: bxl.Context`](../../bxl/Context).
#[starlark_module]
fn dynamic_actions_methods(builder: &mut MethodsBuilder) {}

Currently it's necessary to write boilerplate get_methods implementations just to get docs for opaque types. This could be made easier in the generator by taking the doc string from the starlark_value impl and obviating the necessity for this hack.

lf- avatar Jul 14 '25 19:07 lf-