it's hard to keep macro and rule documentation in sync

[dgoldstein0]

macros generally wrap commonly-used patterns of rules to make them easier to write. As such a very common pattern is to have the macro take a bunch of arguments and forward most of those verbatim or near-verbatim to various rules. The trouble is that when these patterns are combined with stardoc documentation, it ends up being necessary to repeat the same documentation for each rule attribute in the macro's docstring. If there were some way for the macro to refer to the rule attributes documentation, it would cut the docs that we need to write in ~half for these cases - or possibly even more when the same attribute is shared between several rules and many macros.

In practice, much of the macro documentation in the codebase I work in is actually incomplete because it's just too much effort to manually duplicate it all.

[thomasvl]

It sorta sounds like this might be a dup of #27

[dgoldstein0]

yeah, essentially the same problem, though I didn't propose a solution.

In addition to the "macro wraps a rule" case, it'd also be nice to also support the case of a macro that splits it's arguments between a few rules, and avoid repeating the attribute documentation for the macro docstring. It's possible the proposed solution in #27 will solve that second use case too.

I would not object to this being closed as a dupe; thanks for pointing out the other ticket, I'm now subscribed there.

[larsrc-google]

Duplicate of #27

[larsrc-google]

Duplicate of #27