Raku
sub MAIN needs better examples
The problem
The current entry for sub main is lacking some details and examples. For example, how does one create the entry for arguments that are boolean only, or must have values? The current examples do show that but hide the answer while trying to cover too many esoterics too early (such as a muddled description of aliases).
Suggestions
I would like to see examples that clearly define the inputs desired, and then show how to do it with MAIN. A simple example with one optional boolean entry and one required value entry would be a start.
One question that I have after reading the information is: Before the unit sub MAIN declaration, are there any restrictions on using modules or placing file scoped variables?
Yes, and, since I just solved my problem with it, I will try to improve the docs at least a “wee bit” (alluding to next Perl conf :-D).
(But I can’t promise an immediate fix.)
To me the documentation is at best misleading; see this thread for details: https://www.nntp.perl.org/group/perl.perl6.users/2018/07/msg5219.html
https://stackoverflow.com/a/29704107
This answer on SO might be of some help. Just like tbrowder says, instead of jumbling several cases, it's better if each example tackles one feature of MAIN at a time.
@tbrowder let me know how I can help with this one.
While working on docs issue https://github.com/Raku/doc/issues/4395 (documenting named arrays), I also added some subheadings that break up the very long section full of the "jumbled" examples, which is kind of a first step toward sorting them out a little. I'll be keeping an eye on this issue (2167).
