Document the hash form of the build META6.json attribute

[JJ]

That form is only used in this module, does not seem to be documented anywhere. Be it an experimental form or a spec way of using zef, it should be documented so that anyone in the community can use it for her own modules.

Context

This behavior of the depends attribute, which is apparently defined here:

zef/lib/Zef/Distribution.pm6

Lines 68 to 76 in 7c9d05b

	# make matching dependency names against a dist easier
	# when sorting the install order from the meta hash
	method depends-specs {
	my $deps := $.depends ~~ Hash
	?? $.depends<runtime build>.grep(*.defined).grep(*.<requires>).map(*.<requires>).map(*.Slip)
	!! $.depends;
	$deps.grep(*.defined).map({ Zef::Distribution::DependencySpecification.new(system-collapse($_)) })
	}

shows that there are two possible keys, build and runtime, and that each of them needs a requires field which seems to have the form of a list of dependencies. However, the rest of the fields which are used in the module above, from, bin, are not documented anywhere.

Expected Behavior

zef is the default, and for the time being only, module manager in Perl 6. Its behavior should be documented so that it can be used by anyone, and easily replicated by other module installers that might arise in the future.

Actual Behavior

I haven't found any documentation, not even as inline documentation. The zef wiki is empty. The test which uses the feature is neither linked nor documented, and as a matter of fact does not use (and thus test) the bin value for from which is used in the other example of this feature.

Your Environment

This is the source of zef at commit 9cb53c8

[ugexe]

I don't know that the hash form ( meaning the "depends" : { } form, not "depends" : [ {} ] ) will stay or not, nor is it fully implemented -- hence it not being documented in zef.

[JJ]

As far as I understand it, there's a next generation zef which is not officially bundled with Rakudo Star. Experimental|non documented features would be best kept in experimental|non officially released branches or repos, because as long as they're released and used "in the wild", they are bound to be seen (and people will feel confused about them and/or will want to use them for their own purposes).
Also, these features are going, and will be, used in unforeseen (by the user or the feature or the creator of the feature) ways (as I have commented elsewhere #222, META6.json could be used simply as a vehicle for expressing dependencies for an app with nothing to install). In this case, Module Citation as well as p6-river read all META6.json in the ecosystem and will of course fail when they find this undocumented feature. "Toaster" modules such as Blin will suffer the same fate.
My point is that documenting it or not does not depend on it being experimental or not, but on the fact that as long as it's there, even in a single module, it's bound to be consumed by other modules, that will fail if it's not.