Thanks for having a look at Docile.jl. I’ll try to explain some of
my decisions regarding it’s design.
*Introducing a new AST object:*
Having something built into the language would be great and I’d
definitely support that. There’s been some discussion, I think, about
doing that - probably in this thread or another from earlier, perhaps on
GitHub.
I needed something that works now and wouldn’t need changes to any
internals, hence the use of macros for this.
*Using comments rather than strings:*
A much earlier version of Docile.jl did do this, in part, but what I
found was that since comments get discarded during evaluation of the
code this required a separate run to capture documentation. I may have
missed a few tricks to get that to work though.
Another gripe I have about using comments: unless you use some special
syntax/tag (such as the extra # character) to denote what is actually
documentation and what isn’t then commenting out code temporarily
*could* cause problems if docstrings are parsed by Julia “as valid AST
objects”. Using a docstring “tag” to avoid this would work I think, so
long as it *visually distinguishes* plain comments from docstring
comments.
*Metadata in the docstring/comment:*
##
# docstring
#
# Metadata {
# key1 => value1
# }
#
# Examples
# ========
An earlier version I had did embed the metadata directly into the
docstring using the YAML.jl package. Switching to an actual Dict
simplified the code and also makes it easier to generate metadata
programmatically if necessary.
*Readability of @doc:*
I think that this probably just comes down to personal preference for me -
I’ve not done an extensive comparison between different syntax.
@doc introduces a docstring and seems pretty straightforward to me. It
explicitly states that what follows is documentation. That example from
Docile.jl could probably do with some simplifications since that metadata
section looks terrible if I’m honest. Something like the following might be
better as an initial example:
module PackageName
using Docile
@docstrings # must appear before any `@doc` calls
@doc """
Markdown formatted text goes here...
""" ->
function myfunc(x, y)
x + y
end
end
And then leave introducing metadata until after this since I’ve found
metadata to not be needed for every docstring I write.
I’m not sure about the “clearly visible bounded block” though, what in
particular could be clearer? I’m asking since I’ve been staring at these
for a while now and have become quite accustomed to them.
— Mike
