Support a `macro` without a `doc` value but with `inherit_attrs` referring to another `macro` or `rule` inherit that `doc`

[thomasvl]

As seen via #287, should the lack of a doc value to macro pick up a value via inherit_attrs just like the attr values are picked up/merged? i.e. - the lack of a doc value, but presents of an inherit_attrs also allow the general docs to be inherrited?

[tetromino]

I don't understand why users would want such functionality. The wrapper macro exists because it does something different from the wrapped macro, right? Instantiates additional targets, hard-codes some dependency by team policy, etc. - and surely you would want to describe that in the doc string; and if you forgot to write the doc string, you would want to be able to quickly notice.

[thomasvl]

I don't understand why users would want such functionality. The wrapper macro exists because it does something different from the wrapped macro, right? Instantiates additional targets, hard-codes some dependency by team policy, etc. - and surely you would want to describe that in the doc string; and if you forgot to write the doc string, you would want to be able to quickly notice.

Two cases we were thinking -

1. We have a rule sorta like test_suite, where the rules must have some targets. However, we want to wrap it in a finalizer=True macro so that if targets is unsigned, we can collect things from the current package. The actual rule docs don't need to change, instead we just need to override the targets attribute to inspect it and auto populate it.
2. Your company is leveraging rule/set of rules from somewhere else; but slightly customizes things to your companies needs. Rather than taking a fixed snapshot, editing it, and then having to worry about merging in updates, you could use macro to simple wrap the others, but provide your own customizations for the defaults for attributes, provided explicit values so some attributes can't be overridden, etc.

In those sorta cases, it seems like wanting to be able to generate documentation where you only override the attributes is all you need instead of having to completely replicate the documentation for the entire rule.

If you didn't want this to be the default behavior, maybe some marker/value to be able to explicitly inherit the doc value so authors have to do something to opt into this case?

[tetromino]

Thanks for the explanation.

If you didn't want this to be the default behavior, maybe some marker/value to be able to explicitly inherit the doc value so authors have to do something to opt into this case?

I agree that's probably a better way to go. Maybe something like a doc field on rule/macro callables, so you could e.g. do macro(doc = other_macro.doc, ...)?

[thomasvl]

I agree that's probably a better way to go. Maybe something like a doc field on rule/macro callables, so you could e.g. do macro(doc = other_macro.doc, ...)?

I like that, cause it could scale to attributes also, that would allow one to easily override an attribute to change a default, but keep the docs the same.

A stretch would be to support something like:

macro(doc = other_macro.doc + " extra info added to the inherited value.", ...)