Raku
Suggestion for option for simplified view of signatures
Problem or new feature
This struck me recently (I think during Bruce Grey's talk at the recent Conference in the Cloud https://tprc2021cic.sched.com/event/jLxr/raku-the-big and https://www.youtube.com/watch?v=lRGRL_sVRSk) that it can be intimidating to read Raku signatures, but frequently I don't need all the information they have. E.g., for https://docs.raku.org/type/Str#routine_substr is it substr('place to start', 'number of chars') or substr('number of chars', 'place to start')? The doc entry has signatures like method substr(Str:D $s:, $from, $chars? --> Str:D) and I have to know about type smilies, return values, etc, and this isn't even the most complicated signature.
Suggestions
Maybe an little toggle on each page, e.g., 'Simple signature on|off'. Then the simple form of the above example might be something like method substr($from, $chars? --> Str), i.e., removing the invocant, types of parameters, and any type smilies.
Alternate suggestion: have link to signature syntax; This reduces the amount of work needed by doc team (same link at every method vs. creating a modified syntax/writing code to simplify it).
We had a similar discussion in the early days of documentation where a perldoc shorthand style for arguments was proposed. We have a robust syntax for signatures, I'd prefer to use it.
This hardly can be done.
A very dense syntax is one of Raku features (not in a "nice feature" sense, but as "an attribute" of the thing), you pack a lot of sense in a small chunk of code.
People who learn Raku would have to learn all the things mentioned earlier or later, hiding it won't really prevent this need in any way.
Striping off the type information is also not very helpful: the languages gradually going into "more typed" direction rather than the opposite. The suggestion itself sounds good, it fights for all the goodness and tries to be pleasant to everyone, but it's not really possible to please everyone at once here. so I'd at least preserve what's called Raku inner characteristic.
I agree with Altai-man, that providing stripped down signatures is not a good idea in that it leaves off information and does not incentivise learning. I also like the idea of Coke to provide an overview of signature syntax and linking to it. In general I like it when documentation systematically lists signatures when a routine is explained. The documentation can still be improved in this regard.
I'd say systematically adding signatures to routines in the documentation is not part of this ticket. If we decide to aim for Cokes solution to add a link to an introduction to signatures, then having that would solve this ticket. Do we currently have a special syntax to mark signatures in the documentation? I think that would be a prerequisite for providing a link to some signature intro at each signature.
Methods can be marked with :method to assist with examples compilation testing, but there is also a heuristic so that we don't have to tag every item. We could build on :method and add another attribute to the pod block to indicate it should have a link to the signature docs (but have anything already marked as :method count, I'd guess), but whatever generates the HTML would have to process that.
@coke I guess the rejection targets the original idea of stripped down signatures. Is there a follow up ticket for the related ideas of having a signature documentation linked at signatures in the docs?