Hi Leah, thanks for the explanation. That makes a lot of sense.
On Monday, September 15, 2014 12:48:37 PM UTC-5, Leah Hanson wrote: > > The @doc macro lets you do things that the doc_str can't: > > 1) Attach to the following method/function/etc. The string just sits > there; the macro can do the work to put the string into the documentation. > (the doc_str wouldn't be able to see the context around the string it's > parsing) > 2) Add a metadata dictionary after the doc string. > 3) Allow other formats of documentation string (rst, asciidoc, whatever) > as long as the implement some interface of functions (likely some writemime > methods). Something like `@doc rst" ...rst formatted text"`, where using > `doc" text"` would remove the possibility of format tagging via rst_str. > > -- Leah > > On Mon, Sep 15, 2014 at 12:37 PM, Gray Calhoun <[email protected] > <javascript:>> wrote: > >> I should add that I'm excited to try out the package as is and >> successfully document my functions. >> >> >> On Monday, September 15, 2014 12:36:03 PM UTC-5, Gray Calhoun wrote: >>> >>> 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. >>>> >>> >
