Julia: Should docstrings attach inside `begin` blocks

[Keno]

e.g. the following does not currently attach a docstring

    """
    abc
    """
    f(x) = 1
end

It's a one-line change in the parser, but I wanted to check whether there was any intention behind this first. cc @JeffBezanson

[Keno]

For future reference the one-line change is:

diff --git a/src/julia-parser.scm b/src/julia-parser.scm
index 984ebfd..4aff192 100644
--- a/src/julia-parser.scm
+++ b/src/julia-parser.scm
@@ -1083,7 +1083,7 @@
        ((begin quote)
         (let ((loc  (begin (skip-ws-and-comments (ts:port s))
                            (line-number-node s)))
-              (blk  (parse-block s)))
+              (blk  (parse-block s (lambda (s) (parse-docstring s parse-eq)))))
           (expect-end s word)
           (let ((blk  (if (and (length> blk 1)
                                (pair? (cadr blk)) (eq? (caadr blk) 'line))

[tkelman]

thought it was intentional that docstrings are only implicit at toplevel

[Keno]

I wasn't sure. I came across a case where somebody had a docstring which wasn't being attached, and it was because they were being defined in a begin block. I feel like this is a pretty easy mistake to make.

[musm]

let 
global foo

"""
hi
"""
foo(x) = x
end

Also does not attach a docstring to foo, which it should since foo if global

[musm]

I guess the work around would be the following

"""
hello
"""
function foo end

let
global foo

foo(x) = x
end

[bramtayl]

I'm not sure I understand the logic here. I have a recursive macro that I want to be able to run on huge blocks of global code. But to do so everything needs to be inside a begin block, which means I can't define docstrings.

[KristofferC]

How about:

julia> begin
           @doc "A test function" ->
           test_function(a) = "testing"
       end
test_function

help?> test_function
search:

  A test function

[bramtayl]

Sure, that works, but if there's a simple change to avoid the macro, why not? Is the issue that begin blocks inside other non-global blocks and global begin blocks aren't distinguished by the parser?

[StefanKarpinski]

Unless some rationale for the behavior is given, I propose that we apply @Keno's one line patch.

cc @JeffBezanson

[tkelman]

@MichaelHatherly can you recall a justification for only treating strings as docstrings if they're at top level?

[MichaelHatherly]

Was a while ago, but I seem to recall that it was just a case of starting out with the simplest option (just toplevel docs), and then see whether there was much demand for anything else. I can't see any reason not to allow it in begin blocks.

[tkelman]

closed by #20198