Docstrings with Julia/Atom

#1

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
#2

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

#3

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.

#4

Attaching docstring to modules might be the closest to it.

#5

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
...
#6

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.

#7

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.

#8

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.

#9

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

#10

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