Docstrings with Julia/Atom

I am looking at code written about a year ago and successfully run within atom with — probably — Julia 0.5. I can’t even get started now. It is possible I am forgetting some basic stuff, as I haven’t used Julia in about a year and the mind forgets.

I’m on MacOS. I have installed the latest Julia (0.63). I have installed the latest Atom (1.28.0). I have the following updated packages: Hydrogen, language-julia, julia-client, linter-julia, uber-juno,

I can successfully execute cd("/Users/myname/julia/") in the Julia console and in the atom REPL, but get an error when I attempt to execute the whole file preceded by docstrings. Has the syntax for docstrings changed? My usage seems to be consistent with the answer here (unless I’m missing something):

""" 
	blabla
"""

## blabla 
cd("/Users/myname/julia/")

Here is the error message:

ERROR: LoadError: cannot document the following expression:

cd("/Users/myname/julia/")

Stacktrace:
 [1] error(::String, ::String, ::Vararg{String,N} where N) at ./error.jl:30
 [2] include_string(::String, ::String) at ./loading.jl:522
 [3] include_string(::Module, ::String, ::String) at /Users/myname/.julia/v0.6/Compat/src/Compat.jl:88
 [4] (::Atom.##112#116{String,String})() at /Users/myname/.julia/v0.6/Atom/src/eval.jl:109
 [5] withpath(::Atom.##112#116{String,String}, ::Void) at /Users/myname/.julia/v0.6/CodeTools/src/utils.jl:30
 [6] withpath(::Function, ::String) at /Users/myname/.julia/v0.6/Atom/src/eval.jl:38
 [7] hideprompt(::Atom.##111#115{String,String}) at /Users/myname/.julia/v0.6/Atom/src/repl.jl:67
 [8] macro expansion at /Users/myname/.julia/v0.6/Atom/src/eval.jl:106 [inlined]
 [9] (::Atom.##110#114{Dict{String,Any}})() at ./task.jl:80
while loading untitled-8b0c8bf366079a4b60396bc23cf86087, in expression starting on line 2

What is the use case for this? What are you trying to document with this docstring?

1 Like

It is not possible to add a docstring to a function call; generally, all docstrings need to be attached to some kind of object (e.g. a method, function, or constant). You cannot attach a docstring to a whole file.

1 Like

Attaching docstring to modules might be the closest to it.

1 Like

I always have a docstring immediately before the module, works well with the help system. For example:

__precompile__(true)
"""
API Tools package

Copyright 2018 Gandalf Software, Inc., Scott P. Jones

Licensed under MIT License, see LICENSE.md

(@def macro "stolen" from DiffEqBase.jl/src/util.jl :-) )
"""
module ModuleInterfaceTools

We even would use a “dummy” module for documentation purposes, for files we included directly.

"""
Brief description

Copyright info

License Info

(optional) full description
"""
module Foobar end
...
1 Like

Oh thanks. I see that I was not using the docstrings properly. Most likely I didn’t use to execute the whole file and had used the docstrings merely as a comment/info at the top. My bad.

Immediately after the cd("/Users/myname/julia/") command I load a module with include("module.jl"), so perhaps I intended the docstrings to document the module but placed them in the wrong file.

Thanks all of you for the feedback. Sorry for the lame question.

Thanks for providing an example of use. Very useful!

For multiline comments not intended to be docstrings, I’ll use #= and =#, which I didn’t know / forgot about.

If you made an effort (i.e. tried to find an answer in the docs / googling), then no question is lame, so don’t feel sorry.
For quick responses, you might want to try either Gitter or Slack.

2 Likes

Thanks Scott, first time I hear of Gitter. Just signed up.

Looking forward to seeing you in the Julia room: https://gitter.im/JuliaLang/julia

1 Like