On Monday, September 15, 2014 9:39:19 AM UTC+2, Rafael Fourquet wrote:
>
> 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.
>>
>
> Python, despite using docstrings, is a great example of a language having
> "a simple syntax that ... understand"
>
The problems of Python docstrings:
- no standardization on formatting (Markdown vs others).
- loss of debugger trace while testing doctests and/or docexamples (this
is due to the code-to-string-to-code conversion).
- documentation examples are usually not recognized as code by IDEs
(e.g. PyDev in Eclipse), so you don't get completions and code analysis.
- I would prefer the documentation to precede the function declaration.
> I believe that a tagged comment is much more readable than a block
>> introduced by @doc or doc.
>>
>
> "Much more readable" is maybe a bit exaggerated, can you explain why you
> believe so?
>
Take an example from Docile.jl
module PackageName
using Docile
@docstrings # Call before any `@doc` uses. Creates module's `__METADATA__`
object.
@doc """
Markdown formatted text appears here...
""" {
# metadata section
:section => "Main section",
:tags => ["foo", "bar", "baz"]
# ... other (Symbol => Any) pairs
} ->
function myfunc(x, y)
# ...
end
@doc "A short docstring." ->
foo(x) = x
end
The @doc keyword looks confusing to me. If you get used to it, it's OK, but
such a syntax steepens the learning curve to get into Julia, as a new user
(maybe who's not very acquainted with programming) may find it difficult at
first to distinguish the documentation code from the algorithmic code. I
believe that documentation should be a clearly bounded block, possibly
resembling a comment, yet it should contain substructures corresponding to
special AST objects.
In Docile.jl, the @doc macro does not define a "clearly visible bounded
block". I would prefer Julia to introduce a new kind of block formatting
for documentation.
