On Mon, Dec 9, 2019 at 10:25 Simon Proctor <simon.proc...@gmail.com> wrote:
> I *highly* advise learning how signatures work. > This, this, a thousand times this. ToddAndMargo, I have watched you on these lists and on GitHub issues for years. I’ve engaged a few times but have generally pulled back again, always in reaction to the same pattern of behavior: 1. You ask a question about something. 2. It is explained in various ways until you say you get it (and offer sample code to show that you do, indeed, seem to get it). 3. You complain the docs do not describe it in a way that you (or anyone—you frequently invoke yourself as the avatar of the “ordinary programmer” as opposed to, for example, the “IEEE member”. 4. You’re invited to fix the docs. You do not. (Here’s where I’ve engaged more than once: suggesting specific new text and asking if it would have clarified for you. You’ve either ignored it or simply replied that it would not without further constructive feedback.) 5. And then—a few months later, you bring the very same issue up in slightly different form. If, as you implied when suggesting your “grand idea”, you believe you are capable of writing decent documentation, may I suggest you do so in any form whatsoever—and then start referring to it *yourself*? Then, perhaps we could start to have your repetitive complaints be repetitive only in form and not in substance as well, which would at least constitute some sort of progress. But as for the particular issue you’ve homed in on and for which you’ve used such disparagement: it’s been observed by at least six different people in the past couple of years (just from searching my mail) that your eyes seem to slide over signatures, and they seem to offend you (as this “IEEE” comment reiterates), so you gain no insight from their being there. Perl 5 is not a language where signatures are precise enough to lend much insight, so it’s totally unsurprising that its docs do not rely on signatures beyond extremely schematic ones (“LIST”, “VARIABLE”, “EXPR”)—which you find easier to understand. Fine. But Raku, on the other hand, is a language that has pushed its syntax into signatures at a level that I think might be unique among languages (at least insofar as how many things can be done with those signatures that would ordinarily be in the language grammar). This may seem unPerlish, but it has had the enormous advantage of giving Raku the Perlish “DWIMminess” while still having an actual specification, so as to avoid Raku repeating Perl’s issue of being an “empirical language” that can only be defined by its own implementation. It also allows library programmers to do language munging in ways that previously often required complex and fiddly messing around with Perl innards, often in XS or C. So: Signatures are important to Raku. *Extremely* important. Your demand that they be swept under the rug and hidden from docs because they’re cryptic to you is unreasonable. Learn how Signatures work—books, blog posts and tutorials are available to explain at least the basics, and the Signature class’s docs itself is quite readable. Then, and only then, will you be in a position to judge whether their prominent inclusion in documentation is an asset or not. Trey
