search

Altai-man / docs.raku.org

Source code of a beta version of the updated docs.raku.org website
Artistic License 2.0
11 stars 6 forks source link

Incomplete code snippets shouldn't have a "Run" button #66

Closed uzluisf closed 2 years ago

uzluisf commented 2 years ago

This can be easily solved by adding the configuration info :skip-test<incomplete code> to the delimited block =begin code. However submitting an issue to call attention to it.

image

Altai-man commented 2 years ago

Are the marks already present in the current Pod for such examples?

uzluisf commented 2 years ago

Yeah, some code snippets already use the :skip-test flag/option (example here).

image image

The downside is that it does away with syntax highlighting.

Altai-man commented 2 years ago

Alright, thanks! I'll look at it.

Altai-man commented 2 years ago

Hmmm. I thought by chance I forgot to consider skip-test directive when deciding if the example is runnable, but no, it's there:

my $lang = $node.config || $node.config ?? '' !! 'raku-lang';

So the code snippets marked as skip-test do not have the run button already.

Maybe the ticket is about "Error occurred" message, but the examples runner works now.

Can you please clarify what is the exact issue here? Absence of highlighting?

uzluisf commented 2 years ago

The issue I was alluding to is that incomplete pieces of code shouldn't have a "Run" button because 1) it signals that it should be runnable and 2) it will throw an error not necessarily related to the documentation around it. Take for example this under the State:

has &!callback;

If I run it, it throws the compiler-time error You cannot declare attribute '&!callback' here;. However if I'm new to Raku this might be confusing because I don't know if that's supposed to showcase something. For example, none of the text around it indicates that this is supposed to happen. Thus, what I'm getting at is that all incomplete code snippets should have that flag in order to avoid any confusion. I supposed it's only a matter of adding the flag to those code snippets but I wanted to raise the issue here first.

Hopefully this clears things up!

Altai-man commented 2 years ago

I see, thanks for clarifying!

And you are right, it's a matter of the code itself having the directive rather than the website trying to guess what to do with it. At least, as we have the Run button now, it's easier to spot those cases and tweak them.