New pod config option: 'signature'

[Altai-man]

See #794 (comment)

Firstly, cast @gfldex, since he is the main inventor of our doc-compiling project.

Since we need to compile signatures(errors occur there too) we need some method/routine/sub body to compile it without error. The thing is, we don't want reader to see this ugly {} empty method body.
Because of that, using @coke advice, I've implemented this option. If you write it like this:

=begin code :signature
    method some(Bar)
=end code

or even like that

=begin code :signature
    method some1(Bar)
    method some2(Bar)
=end code

empty brackets will be added automatically(in second case, for every string respectively).

My English is less than awesome(I guess, it really is), so I'll be really grateful if someone will fix up my bad-written description at the CONTRIBUTION.md page.

It can be merged if @gfldex approves.

[Altai-man]

It sure feels a bit wordy, but some solution like "Let's check it with regexes and hope it didn't break somewhere" or something similar is not cool too.

[AlexDaniel]

What about changing this:

$content.subst("\n", "\{\} \n", :g)

to something like this (untested):

$content.subst(/ [ ')' | returns \s+ \S+ ] <( $$ /, ' {}', :g)

This way it should support multi-line signatures as well. Like the one on Str#split

[Altai-man]

@AlexDaniel my code was tested on all(updated) pages that start with "A" character. I'll try your variant, but it seems a bit more obscure, than mine(or not). If it passes, I'll likely update my pr.
But I'm not completely sure about what to do with multi-line signatures. Maybe this behavior will be changed in the future.

[tbrowder]

On Friday, August 5, 2016, Altai-man notifications@github.com wrote:
...

Because of that, using @coke https://github.com/coke advice, I've
implemented this option. If you write it like this:

=begin code :signature

I think you need to document the new config option in S26. And how about
the Perl 6 grammar and actions in rakudo?

[Altai-man]

@tbrowder, I believe that Rakudo and Perl 6 grammar itself have nothing to do with how exactly we "test" our documentation, it's a separate thing. It is a custom option that is useful for the documentation testing, but it's definitely not mandatory. S26 only defines a presentation. It doesn't say anything about testing the examples. Please, correct me if I'm wrong here.
This test can be changed anytime if needed, hence I don't think we should make it more official then we already did.

For example, someone can implement an another way to test the documentation and just ignore this config option.

If you'll argue that we need to replace explicit signature marking with implicit signature guessing(like 'If there a word method|routine|sub|etc after four spaces and then symbols, but not the {} ones', you can be right. Then we need to revert this and rewrite our examples-extracting code a bit.

I'm not a S26 specialist, but by previously added :skip-test option I assumed, that custom config options are not something scary. Am I wrong?

[Altai-man]

Also, after your comment I thought a lot about implicit detection and now it looks for me as a really better solution than explicit marking.
If we revert this PR and write a method detection, it'll automatically(i.e. without any changes) make all our signatures correct, without adding of two lines for every signature(and we have a lot of them).

[tbrowder]

On Sunday, August 7, 2016, Altai-man notifications@github.com wrote:

Also, after your comment I thought a lot about implicit detection and now
it looks for me as a really better solution than explicit marking.

I'm certainly not an S26 expert either, but I have been dabbling in the
guts of rakudo pod handling and wanted to warn about possible side effects
from defining a pod attribute outside rakudo.

If we revert this PR and write a method detection, it'll
automatically(i.e. without any changes) make all our signatures correct,
without adding of two lines for every signature(and we have a lot of them).

I don't pretend to understand completely, but that sounds better for the
moment. However, I think the more we customize the pod cleanup for the html
output we shouldn't forget that, eventually, we need to convert pod to
other output formats.

[Altai-man]

@tbrowder in fact, the pod testing doesn't affect the html or any other output format. But yes, you're totally correct.
I'm going to revert this and implement signature detection.