Symbolic Macros should generate docs pretty much exactly like rules

[thomasvl]

Symbolic Macros (https://bazel.build/extending/macros) seems like they are meant to cover the case where you really want to create a "rule", but is easier to actually compose it out of one or more other rules. But the generated documentation leaks this details, it calls out that it is a "macro" and not a "rule", but why should the users of the thing care? They should be treating it just like a rule.

• The generated docs for name calls out it is a macro vs a rule.
• The generated docs for name also calls out there could be multiple subtargets, but isn't that an implementation detail?
• The summary block for the macro includes the * before the name, why? Since everything has to be named like a rule, why is this needed? A rule's docs don't include a *?

[tetromino]

I'm open to changing the output to be more useful and friendlier, but it also needs to be correct...

• There is nothing in Bazel which forces a symbolic macro to instantiate a target with the exact name name. It's legal for a symbolic macro to not instantiate any targets at all! It's legal to instantiate targets ${name}_foo and ${name}.bar, but not instantiate ${name}.
• Some auxiliary targets might be implementation details, others might be intended to be parts of the macro's API. However, Stardoc cannot determine this - in fact, it can't even determine the overall list of targets that a macro would instantiate, because that requires evaluating the macro's implementation function for particular (and valid!) values of arguments
• There are situations where rules and symbolic macros behave differently, and you can only use one and not the other. (For example, everything in bazel query is oriented around rules, and macros are elided.)

The lack of * before name on rules is, IMHO, a historical wart. At some point we should add it there for consistency, since Stardoc's output ought to reflect Starlark syntax. (PRs are welcome!)

[thomasvl]

That's fair. I was looking at a case where I have to use a wrapper for other Starlark reasons, and I'd really like to to appear as a rule.

Maybe if it is inheriting all of the information from a "rule" (see https://github.com/bazelbuild/stardoc/issues/288 for the general description part in addition to the attributes), then it should be pretty much exactly like a "rule"; but if it is not inheriting from a rule, then the differences make more sense?

(although I guess even inherit from a rule you could create multiple targets, but maybe that's why then should be providing doc on macro vs. trying to inherit the rule's doc also)