<name> as prefix in types.attrsOf types.submodule is often unhelpful

[Ma27]

Describe the bug

Let's take a look at e.g. systemd.tmpfiles.settings.<name>.<name>.<name>.user.

The line itself is the first thing you get when searching for how to use systemd.tmpfiles on search.nixos.org. The problem is, how am I supposed to know what each of these <name> entries means?
Sure, you can deduce it by looking at the example from options.systemd.tmpfiles.settings, but it would be immediately obvious if it's called like this:

systemd.tmpfiles.settings.<rule-name>.<type>.<path>

(type & path are derived from tmpfiles.d(5)).

One ad-hoc way of solving that is to add some kind of namedAttrsOf function that accepts an argument for the prefix for getSubOptions, however it feels wrong to add a new "type" just for that. Also, namedAttrsOf str doesn't make much sense, it's effectively the same as attrsOf str.

But perhaps the sub-type can provide a "prefix name" to the parent? Like attrsOf (submodule { options = ...; name = ...; })? We should probably force it to be in </> for lib.showOption. Anyways, I know the knobs where to change that, but we should discuss first whether we want this and I'd need some input on how to reasonably design that.

Notify maintainers

@roberth
@infinisil

---

Add a 👍 reaction to issues you find important.

[infinisil]

The pattern that has established itself is to add -With variants, in this case attrsOfWith, which takes an attribute set with more arguments. In this case it could be

attrsOfWith {
  elemType = ...;
  metaName = ...;
}

I'd be in favor of adding something like this :)

[roberth]

I think we can drop the Of, because we don't have a simply parameter for the type.

attrsWith {
  elemType = ...;
  ...
}

Not sure about metaName. Does it only affect docs, or also the module argument?

Context:

• lib/modules: add attrArgName #177576

[infinisil]

Good point on the Of, attrsWith sounds good.

And oh actually indeed, this would effectively implement this and therefore also solve that problem! I still think it should be called metaName though, or at least definitely not name to avoid confusion with the attribute name of the definitions

[roberth]

"Meta" is ambiguous in that name. I assume you want it to take the proper meaning of meta, and not refer to the meta attribute or something like "name for use in metadata".

nameName would solve that, but we can probably do even better.

[infinisil]

Oh yeah. I think metaName would be fine because the true meaning of meta is the only one that makes sense here. Can't immediately think of a better alternative that would not be more confusing, but I'm open to alternatives (definitely not nameName though!).