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