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]> 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. >>> >>
