"Usage" section seems useless to reader

[Altai-man]

In some documentation files we have "Usage" section, like this:

Defined as:

    multi method fmt(Pair:D:) returns Str:D {}

Usage:

    PAIR.fmt(FORMATSTRING)

Judging by grep, we have about 300 occurrences of such "examples". But, eh, is it really useful?

If we explain some method or subroutine, I think, anyone, who reads documentation, do know how to apply subroutines and call methods. For a method it's just value.method-name(maybe-some-args) - this formula doesn't change with every section, we just repeat useless stuff. We don't have any output example to be really useful for anyone in such sections, too. If we apply a function, it'll almost always(yes, perl 6 has many ways to call a subroutine, but that's not the case) be sub-name(value, some-other-args).
Is it me or this "Usage" sections are a bit redundant?

Secondly, because we have "fake" arguments there, like "PAIR" or "FORMATSTRING', it is impossible to check them with a compiler. I think, if we want to really show some usage, we need to rewrite all such strings as a proper examples, if we not, we need to remove such sections.

[jonathanstowe]

I'm more with having the actual signature (pretty much as in the declaration,) and then if necessary some example (or examples,) that show it being used with some example output.

[zoffixznet]

IIRC @dha started adding those Usage sections but then someone raised concerns similar to yours and the work stopped.

They do seem redundant, though personally I'd be OK if those were replaced with actual usage; that is actual code examples, rather than FORMATSTRING, e.g. :foo<bar>.fmt: '%s: %s'

[coke]

I was the one who raised that concern originally.

I believe they are intended to address the issue that to truly understand the signature presented in a perl 6 routine, you might have to understand a lot of extra syntax; The simplified approach is supposed to make it easier to understand.

My concern is that we already have to explain all the details of how signatures work; now we may also have to explain all the details about the USAGE blocks work.

I am fine with going all out with USAGES where needed, but I think we need to document the docs in that case.

If we end up just using function signatures, then we should have quick links/popups to "what this signature means" that are automatically generated.

The current situation with some USAGES and some not is confusing.

[Altai-man]

I believe that actual working examples will be more useful than just repeating of Type.method-name every time.
Signatures can really be strange for a novice(with all this :D:, slurps, etc), but actual example provides an ability to copy-paste code just from the docs and play with it a bit, to understand what is where.
Hence, my suggestion is to replace every Using occurrence with actual example with actual output. I can try to do this using my own time and knowledge, but if someone is willing to spend an evening or two to help me - I'll be really grateful.
If you're against of this replacement idea, please, write out your thoughts here. If you're okay with it, simple +1 will be enough.

Automatically generated signature explanations is not an easy task. I think, we'd better to create/to point to a page with general signatures explanation. We already have subroutines page, where all the details of possible signatures explained.

[jonathanstowe]

The "confusing signatures" could be somewhat alleviated by a link of some sort to the signature documentation which IIRC is quite complete (or should be by now.)

[ajs]

It seems to me that:

multi method fmt(Pair:D:) returns Str:D {}

Has some real usability problems as docs, but it should be easily translated into something much more docish.

Some rules I'd propose:

• method foo(Bar:D:) should become Bar instance method foo()
• "multi" should be dropped unless required (e.g. we're showing multiple signatures for the same method/function
• We should think about breaking out returns something:D as a separate line: returns defined something
• Remove the trailing {}

So the example becomes:

instance method fmt()

returns defined Str

I'd suggest that's quite readable, but all of the transformations are pretty straightforward (heck, we could build it into Signature as something like .explain

[AlexDaniel]

I agree that we should have more useful examples. “Usage” section will indeed have less value if we provide enough useful examples.
That being said, I don't think that usage sections are “useless” when there are no examples. It is much easier to read than the actual signature (no matter how much you explain them, it is just harder to read). Compare yourself:

multi sub    split(  Str:D $delimiter, Str:D $input, $limit = Inf,
  :$skip-empty, :$v, :$k, :$kv, :$p) returns Positional

split( DELIMITER,  STRING [,LIMIT] [,:v] [,:k] [,:kv] [,:p] [,:skip-empty] )

[moritz]

I really don't like the idea of using things like instance method fmt(), because it's not Perl 6 syntax. If you read the docs, chances are you're already struggling with some Perl 6 concepts, and having to learn yet another syntax doesn't help much, especially when you find out that you can only use the syntax in the docs.

[pmurias]

@AlexDaniel

They are easier to use mainly because they offer less info.

sub split($delimiter, $string, :$limit, :$v, :$k, :$kv, :$p, :$skip-empty) is much easier to read too.

[Altai-man]

@ajs let's see. Trailing {} is needed to compile all signatures. I've already seen(and fixed) places where signatures were wrong. If we are able to compile them - it's good. I don't like the idea of skipping this code pieces.
Separating of signature in two lines seems strange too. We have a few long methods, but we have much more short methods, they will look weird.

It's not the talk about an actual signatures, I suppose, they should be untouched. It's the documentation, not a language tutorial.

[AlexDaniel]

@pmurias I know, you are right. But people trying to learn Perl 6 want something readable to get started, and my point is that “usage” section is not as useless as this issue seems to suggests. It does offer less info, but sometimes that's what you want and need.

However, examples are even more useful, if done correctly. I don't mind “usage” sections go.

[pmurias]

Hovering explanations could help people learn.

[coke]

Don't add {} to sig code. Tag the block and make the test smart enough to add the {} for you

[Altai-man]

@coke it's a good idea, thanks.

[smls]

My two cents:

1. Always show the signatures in proper Perl 6 notation.

2. Make sure that the free-form text + example snippets that follow it, are comprehensive enough to allow a newbie to learn all relevant information about the routine in question, without having to understand the signature.

[Altai-man]

@smls
1)It is already our base if we want to compile examples. The only one tricky point is that some signatures were changed in rakudo(is it from where they were taken? I somewhat doubt that). As example, see
https://docs.perl6.org/type/IO::Spec::Cygwin#method_abs2rel
and then
https://github.com/rakudo/rakudo/blob/8cbb1efd1d84fd57298e0e0813b64d8dd37140ba/src/core/IO/Spec/Cygwin.pm#L44
And yes, our IO::Spec are completely undocumented(but I believe they are similar to Perl equivalents).
If you mean that signatures should be correct, from the point of Perl 6, then we're working on it, since some of them contain typos/errors.
2)We cannot give some math proof of it, but I do efforts in this direction. Many eyes is a good problem detector too.

[jonathanstowe]

IIRC I autogenerated the IO::Spec docs about a year ago, so it is entirely possible that the actual methods have changed in the meantime.

[Altai-man]

@jonathanstowe then it's a time for a new issue for someone to investigate/write/test these pages.

[Altai-man]

With 3029fc1075 last "Usage" sections were removed(you can still grep a few, but they are mostly needed).
We still need a decent example for .ACCEPTS method, but this issue can be closed.

[dha]

As zoffixznet and coke pointed out, this was my work. When coke raised objections, I stopped, but when that happened, I asked if i should remove the usage statements and the response was, "no, don't do that yet" and that was where, AFAIK, it was left.

The discussions about it left me with the following feeling about this general area of documentation: Use the actual signatures, and have sufficient (fsvo) examples in the actual documentation, rather than usage statements. This, however, would, IMO, require very detailed documentation of signatures. jonathanstowe indicates that he thinks such documentation is currently complete, but, as I've been somewhat busy lately and out of the loop, I am not aware of that being the case. A quick look at docs.perl6.org does not have information on signatures jumping out at me, so I'm skeptical on that point.

In any case, if we can have an explicit, obvious, and complete Signatures documentation page, I see no reason why the usage statements can't be removed. And I'll be happy to be the one to do that if we have actual agreement on that point.

[dha]

And now I see that I missed the comment indicating that they have, in fact, mostly been removed and this issue closed. Blah.

I was about to question Altai-man's comment that "you can still grep a few, but they are mostly needed" on the basis of why they'd be needed, but a quick grep shows that they all seem to be gone. shrug

I guess I'll shut up now.

[Altai-man]

@dha
with the latest commit, it looks like this now:

➜  doc-origin git:(master) ✗ grep -r "Usage:" doc/* | sort | nl
     1  doc/Language/5to6-nutshell.pod6:        Usage:
     2  doc/Language/functions.pod6:    Usage: {$*PROGRAM-NAME} [number]
     3  doc/Language/rb-nutshell.pod6:        opts.banner = 'Usage: example.rb --length=abc'
     4  doc/Language/rb-nutshell.pod6:        Usage:
     5  doc/Type/Any.pod6:Usage:
     6  doc/Type/Cancellation.pod6:Usage:
     7  doc/Type/IO/Path.pod6:Usage:
➜  doc-origin git:(master) ✗ 

First four matches are false positives, I wasn't able to come up with a good example for Any.ACCEPTS(if anybody willing to do it, it will be a good thing). Also, example of Cancellation method is missing for the same reason and the last one is a false positive.

About your words about the signatures - yes, I'm completely agree with you in the point that we need a good Signature page documentation. Personally, I don't think that we need signatures explanation in popups, but I'm not against it, so if someone wants to implement such a feature - don't be afraid to open a new issue or even pull request.

Thanks for your comments!