Make macro conventions consistent across documentation
bzl-style.md says to prefix macros with "_". macros.md says not to.
I updated documentation to be consistent the macros.md, because the code in the macros is slightly shorted and because I think the users are mostly not following the convention.
@@ -135,17 +135,15 @@ referenced directly at the Bazel CLI or in BUILD files: In that case, only the
*end users* of those targets need to know about them, and any build problems
introduced by macros are never far from their usage.
-For macros that define internal targets (implementation details of the macro
+For macros that define generated targets (implementation details of the macro
which are not supposed to be referred to at the CLI or depended on by targets
not instantiated by that macro), follow these best practices:
* A macro should take a `name` argument and define a target with that name.
That target becomes that macro's *main target*.
-* All other targets defined by a macro should:
- * Have their names preceded with an underscore (`_`), followed by the
- value of the `name` attribute. For instance, if the macro is supplied
- with the name *resources*, internal targets should have names
- beginning with *_resources*.
+* Generated targets, that is all other targets defined by a macro, should:
+ * Have their names prefixed by `<name>` or `_<name>`. For example, using
+ `name = '%s_bar' % (name)`.
* Have restricted visibility (`//visibility:private`), and
* Have a `manual` tag to avoid expansion in wildcard targets (`:all`,
`...`, `:*`, etc).
@@ -169,6 +167,8 @@ goals.
As a rule of thumb, the more macros resemble the rules, the better.
+See also [macros](/rules/macros#conventions).
+
## Rules {:#rules}
* Rules, aspects, and their attributes should use lower_case names ("snake
