Julia: Better error message when newbies mess up a docstring

[EricForgy]

https://groups.google.com/forum/#!topic/julia-users/3vQAtu9ef6I

I was putting a docstring before a call to a constructor with a DO block (oops!) and the error message could have been more helpful, i.e. from the error, I didn't even realize it was related to docstring. It was suggested on julia-users that I file an issue so here it is :)

[jiahao]

+1

I suspect this scenario happens quite frequently when migrating from Python, where docstrings are placed in strings in many places.

Another instance I encountered recently was

"""
My awesome script
"""

using MyPkg #<--- triggers cryptic error

function nothings()
...

[MichaelHatherly]

The current error printed for the using MyPkg case is

ERROR: LoadError: invalid doc expression:

@doc "..." using MyPkg

 in error at ./error.jl:22
while loading /home/mike/test.jl, in expression starting on line 1

on both 0.4 and master. Perhaps slightly cryptic since the docstring contents isn't shown, though I went with not displaying it since I found it cluttered things up with larger docstrings. If there's consensus to rather show the contents as well then that can be added easily.

[IainNZ]

That error message is pretty rough in a lot of ways. The lack of contents isn't the main thing - more the mysteriously-appearing @doc and no explanation for why its invalid. I could maybe help with the message, if its not a limitation of the parser or something.

[MichaelHatherly]

Yes, @doc can go, that was probably just left over from when we only had @doc syntax and no bare docstrings. Regarding explanation for invalid perhaps we should link to the manual section that outlines all the supported syntax in the error message. Something like

ERROR: LoadError: cannot document the following expression:

    using MyPkg

See http://docs.julialang.org/en/latest/manual/documentation/#syntax-guide
for the full list of supported syntax.

 in error at ./error.jl:22
while loading /home/mike/test.jl, in expression starting on line 1

or do we want to list out the supported syntax within the error message?

[IainNZ]

I'd actually find cannot document the following expression sufficient, as I think I'd be able to realize that Julia thought I wanted that string associated with the using line. Not sure the link is needed, although adding links could be neat if we did it consistently.

[MichaelHatherly]

The error message in #16368 has been reworded to use cannot document the following expression without the link to the manual section.

[MichaelHatherly]

Closed by #16368.

[cossio]

Why is this an error? I thought you were free to put strings wherever you desired.