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
