Just to engage in some bikeshedding.... is @doc better than defining
doc_str or d_str? The triple quote notation seems like an unnecessary
pythonism. doc_str gives:
doc"
Markdown formatted text goes here...
" ->
function myfunc(x, y)
x + y
end
On Monday, September 15, 2014 10:02:49 AM UTC-5, Michael Hatherly wrote:
> *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.
>
