either does not propagate suboptions

[ncfavier]

An option with the type either foo (submodule ...) (or oneOf [ (submodule ...) ... ]) will not have the suboptions of the submodule appear in the manual. This popped up in #191768 (comment).

The obvious fix would be to add something like getSubOptions = prefix: lib.attrsets.unionOfDisjoint (t1.getSubOptions prefix) (t2.getSubOptions prefix); to either, but this results in an infinite recursion because of recursively defined types like (pkgs.formats.yaml {}).type:

nixpkgs/pkgs/pkgs-lib/formats.nix

Lines 73 to 85 in 946eafd

	type = with lib.types; let
	valueType = nullOr (oneOf [
	bool
	int
	float
	str
	path
	(attrsOf valueType)
	(listOf valueType)
	]) // {
	description = "YAML value";
	};
	in valueType;

Generating the documentation for an option foo of that type will try to get the suboptions for foo, which will recurse to get the suboptions for foo.<name>, then foo.<name>.<name>, etc.

We could hack our way around this by overriding getSubOptions manually for recursive types, or setting a maximum recursion depth, but I can't really think of an elegant solution to this. Maybe we should just live with it, and document that submodule in either is not supported.

cc @infinisil @roberth

[roberth]

Perhaps recursive types should be defined through an explicit fixpoint? That way the fixpoint combinator can take care of plugging the infinite recursions for this, description and future such problems.

boolTree = types.fix (t: oneOf [ (attrsOf t) bool ])

types.fix = tf: lib.fix tf // { description = "recursive type of ${tf (types.null // { description = "the recursive type"; })}"; getSubOptions = ...; }

Not great, but certainly not terrible.

[ncfavier]

That's probably the least bad option.