Inline code in the docs - the correct way

H. S. Teoh hsteoh at quickfur.ath.cx
Wed Jan 31 21:34:47 UTC 2018


On Wed, Jan 31, 2018 at 06:31:34PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Wednesday, 31 January 2018 at 17:14:56 UTC, H. S. Teoh wrote:
> > But otherwise, the two are equivalent. (In fact, backticks translate
> > directly into $(D ...) in the ddoc code. They are just syntactic
> > sugar.)
> 
> No, they aren't. The `` is different in several ways including doing
> character escaping that macros are incapable of, and it expands to
> BACKTICK, not D. Read the comment of mine linked by the OP.

Ah, then I stand corrected.


> They are intended to be separate, but you are right that the lighter
> syntax is getting more attention, much to my chagrin.

Coming from you, I'm a little surprised.  Weren't you one of the people
complaining that ddoc macro syntax is ugly?  I actually share that
sentiment, and have been avoiding using any explicit macro markup in my
ddoc comments until `` came along that didn't make the source code (IMO)
unreadable.  Even now, I still refuse to use anything more than that in
my own code, at least not directly (I did do one or two ddoc template
customizations, but would not insert that into my source code itself).
Though of course, when contributing to Phobos I just have to follow
whatever other Phobos code does.  (Still, I try to avoid touching ddoc
macro syntax where possible. It makes me feel like I have to wash my
hands afterwards.)


T

-- 
One reason that few people are aware there are programs running the internet is that they never crash in any significant way: the free software underlying the internet is reliable to the point of invisibility. -- Glyn Moody, from the article "Giving it all away"


More information about the Digitalmars-d mailing list