On Saturday, September 13, 2014 2:26:18 AM UTC+2, Michael Hatherly wrote:
>
> Hi Francesco,
>
> Docile.jl partially covers what I think you're wanting out of your
> docstrings, namely testing examples for correctness. I've been thinking
> about exporting the docstrings to ijulia notebooks which might provide a
> more interactive experience in some cases.
>
>
Docile.jl looks great, but I think that the API should be made into
comments. One of Julia's goals is to have a simple syntax that even people
who are not acquainted with programming can easily understand.
I still think that the best solution would be to create a new AST object to
handle blocks of comments tagged as documentation. Maybe blocks of comments
starting with # followed by a special character. I also think that
documentation examples/tests should also be parsed by Julia's parser as
valid AST objects, that is blocks containing input code and expected
answers.
I believe that a tagged comment is much more readable than a block
introduced by @doc or doc.
Possible examples:
##
# docstring
#
# Metadata {
# key1 => value1
# }
#
# Examples
# ========
#
# julia> f(3)
# 9
#
function f(x)
x^2
end
or an other idea:
#=
docstring for square number [references.wikip]
.metadata {
key1 => value1,
key2 => value2,
...
}
Examples
========
julia> f(3)
9
.references (
wikip : https://en.wikipedia.org/wiki/Square_number
)
=#
function f(x)
x^2
end
