Inline code in the docs - the correct way

[H. S. Teoh]

On Fri, Feb 02, 2018 at 07:46:51PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Friday, 2 February 2018 at 18:45:50 UTC, H. S. Teoh wrote:
> > In an ideal world, you wouldn't need to encode any of this stuff
> > inside a ddoc comment.
> 
> Well, that's what the Phobos REF macro does... sort of. You write
> $(REF symbolName, std, module) and the macro figures out the link.
> Though, even that macro is based on the url structure on dlang.org...
[...]

Well exactly, and that's the problem. The macro arguments require
knowledge of the URL structure on dlang.org.  And also knowledge of the
FQN of the symbol. When the FQN changes, you have to update *every link*
that refers to that symbol.  That's like coding in the bad ole days
before encapsulation was a common practice. Everything depended on
everything else, and changing one small thing causes a ripple effect
that requires touching the rest of the code in 100 different places.

We should be leveraging what the compiler is already capable of doing,
and keep the docs agnostic of the nitty-gritty details of the symbol's
FQN or where it might reside in the URL tree.  It's plain and simple
encapsulation, as applied to docs.


[...]
> >  Since ddoc comments are processed by the compiler, and the compiler
> >  has all of the information necessary to resolve identifiers,
> >  arguably all that *should* be needed is just a way to indicate in
> >  the docs, "this word is an identifier", and the compiler would
> >  figure out what it's referring to, perhaps expand it into a
> >  fully-qualified name like std.range.primitives.isInputRange.
> 
> Right, this is exactly what adrdox does and it has been a smashing
> success to me. It'd be nice if ddoc did it too (at least so I don't
> have to deal with so many merge conflicts on the broken phobos source
> links!)
[...]

This is the kind of thing you should be promoting to Andrei to convince
him that dpldocs is better. ;-)


T

-- 
Today's society is one of specialization: as you grow, you learn more and more about less and less. Eventually, you know everything about nothing.