adrdox vs markdown vs ddoc

[H. S. Teoh]

On Thu, Feb 01, 2018 at 05:33:21PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Thursday, 1 February 2018 at 06:18:52 UTC, Seb wrote:
> > To be fair, I feel with you and all the tables I have created are
> > formatted as good as DDoc allows, e.g.
> 
> Yeah, that's not bad, really. I think that's actually significantly
> better than the Markdown table syntax - adding a new function or
> category there is pretty easy and it is legible enough in the source.

I still prefer Markdown table syntax.  But then again, I hardly ever
need to put tables in my ddocs anyway, so perhaps that's just an
uninformed opinion.


> [...] Actually, I saw a debate over /** */ vs /++ +/ too, and I'm
> pretty firmly on the /++ +/ side of it. Almost every time I write docs
> and do /** or even ///, I regret it because I want to change it to /++
> later anyway so I can have commented code samples in the docs.
[...]

I actually like the /** */ syntax, with the stars that horrify you so
much. :-D  Mainly because vim automatically formats them for me, so I
never actually have to fiddle with the stars myself, and I do like long
block comments being clearly standing out from the rest of the code.

As far as nested comments are concerned, I'm a firm believer in ddoc'd
unittests, so I hardly ever bother with inline code examples, much less
ones that need comments, and pretty much never ones that need block
comments.

I do agree about ///, though.  Except for `/// ditto`, I almost
invariably regret writing /// anywhere because they almost always need
to be expanded into /** */ later on.  They're convenient for when I'm
too lazy to write docs for enum members, but when polishing up docs,
they basically always need to turn into /** */. So they're good for
laziness, but not much more.


T

-- 
"Computer Science is no more about computers than astronomy is about telescopes." -- E.W. Dijkstra