buildtools icon indicating copy to clipboard operation
buildtools copied to clipboard

buildifier lint should not warn about missing common definitions in docstrings

Open aiuto opened this issue 1 year ago • 0 comments

buildifier will warn if you specify a common attribute in a macro wrapping a rule, but then do not document it.

This creates needless churn because the documentation really belongs at https://bazel.build/reference/be/common-definitions instead of replicated to each rule. When developers essentially copy definitions from there, they are like to get content and formatting wrong. If they just add a link, like See [Common Attributes](https://bazel.build/reference/be/common-definitions) they are doing something brittle w.r.t the bazel team restructuring the docs.

You should be encouraged to leave out the things that can be lifted from the common definitions and/or the rule definition that a macro is wrapping. Stardoc should be the one that replicates text if that is the desired doc presentation style.

aiuto avatar Sep 14 '22 18:09 aiuto