Search code examples
commentsrakupod6

Can Declarator Blocks be used on variable declarations?

When I run raku --doc test.raku on the following code:

#! /usr/bin/env raku
use v6.d;

#| The answer
my Int $bar = 42;
#= Thank you, Douglas

say $bar.WHY.leading;
say $bar.WHY.following;

I get no output. When I run the code (raku test.raku), the output is:

Nil
Nil

Is there any way to use Declarator Blocks with variables?

Solution

  • It is syntactically valid to place a declarator comment anywhere; one can even put it on a statement:

    #| Look, a statement
say "hello";

    Rakudo will currently only attach the documentation to packages, attributes, routines, and parameters, since these have meta-objects that have a means to attach documentation.

    By contrast, the Comma IDE also keeps track of documentation comments on variables, and can show them at usage sites of the variable:

    Example of variable declaration in Comma

    An IDE keeping track of them is quite different from a Rakudo implementation making them available at runtime, however.

    If declarator comments were to work on variables, almost certainly one would have to write:

    say $bar.VAR.WHY.leading;

    Because otherwise one would be talking about what is in the variable, not the Scalar (or Array or Hash) container itself. Even then, if one binds:

    #| The answer
my Int $bar := 42;

    Then there isn't a container to attach the documentation to, so there's no way to make it accessible at runtime.

    The upcoming RakuAST (a standardized document object model for Raku code) would allow an opportunity to provide access to declarator docs attached to anything whatsoever (although it doesn't yet); this would still not provide runtime access to the docs, but it would provide a means for tools to parse and extract them.