Documentation Inheritance #27
Description
As explained in bazelbuild/bazel#7977, there's a common use case for macros which serve as thin wrappers on rule invocations. In such cases, it's inconvenient and maintenance-heavy to manually mirror rule documentation as macro documentation:
def _rule_impl(ctx):
bin_output = ctx.outputs.bin_output
...
return [OutputGroupInfo(bin = depset([bin_output])]
_my_rule = rule(
implementation = _my_rule_impl,
doc = "My rule is the best rule",
attrs = {
"bin_output" : attr.output(doc = "Binary output"),
"foo" : attr.string(doc = "Lorem ipsum dolor sit amet")
}
)
def my_rule(name, **kwargs):
"""My rule is the best rule.
Args:
name: The name of the test rule.
foo: Lorem ipsum dolor sit amet
bin_output: Binary output. `name` + '.exe' by default.
**kwargs: Other attributes to include
"""
_my_rule(name = name,
bin_output = name + ".exe",
**kwargs)There are several issues here:
- Duplication between the root and argument documentation in the
my_rulemacro and the_my_rulerule - The Args section of the macro does not appropriately match the rule. There is no "foo" parameter of the macro, but it might be part of kwargs.
- We need not document kwargs, as all kwargs should also be documented in
_my_rule
I propose a macro metatag (for Stardoc to recognize) which effectively notes inheritance of documentation. So instead:
def my_rule(name, **kwargs):
"""@inherit(_my_rule)
Args:
bin_output: `name` + '.exe' by default.
"""
_my_rule(name = name,
bin_output = name + ".exe",
**kwargs)Note this new format will also need to be recognized by buildifier, so that buildifier does not emit warnings even if the Args section of the macro's docstring does not match the arguments of the macro. (Related to bazelbuild/buildtools#649)