Add more notes about intermediary macro targets
Adding some best practice my team has discovered and are practicing for "internal" (intermediary) targets generated by widely-used macros.
Closes
@@ -141,11 +141,14 @@ 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 name attribute. For instance, if the
- macro is supplied with the name *resources*, internal targets should have
- names beginning with *_resources*. They should also have restricted
- visibility.
+* 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*.
+ * Have restricted visibility (`//visibility:private`), and
+ * Have a `manual` tag to avoid expansion in wildcard targets (`:all`,
+ `...`, `:*`, etc).
* The `name` should only be used to derive names of targets defined by the
macro, and not for anything else. For example, don't use the name to derive
a dependency or input file that is not generated by the macro itself.
