Inline code in the docs - the correct way

[H. S. Teoh]

On Fri, Feb 02, 2018 at 10:49:18AM -0700, Jonathan M Davis via Digitalmars-d wrote:
> On Friday, February 02, 2018 15:12:45 Adam D. Ruppe via Digitalmars-d wrote:
> > On Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M Davis
> > > IMHO, the main problem with ddoc for documentation is that it
> > > doesn't automatically handle stuff like cross-links, and it
> > > fundamentally can't, because to do that properly, you have to
> > > generate all of the docs at once with a standard layout for where
> > > everything goes so that the links can link to stuff.
> >
> > Well, maybe, it could do something like adrdox's symbol lookup but
> > instead of generating a link directly, it could replace it with
> > $(REF) and let the macro definitions handle it.
> >
> > Wouldn't be perfect tho, that macro is clunky to use and define
> > because it doesn't know all the details, but it would be a move up
> > from what we have, and may even work inside code examples.
> 
> I thought about that, but it falls flat on its face as soon as not all
> of the user-defined types are from the library being documented. The
> simplest example would be if I were to publish my own library but it
> used types from Phobos in its API. Turning those types into links
> would then try to link to my project's documentation, which wouldn't
> work. Best case, I could create redirects to the Phobos docs, so that
> might work, but it gets messy fast, and any types from 3rd party
> libraries which were used in the API would have the same problem.
> Somehow, the links would have to be made to work regardless of whether
> the types were part of the project being documented.
[...]

In an ideal world, you wouldn't need to encode any of this stuff inside
a ddoc comment.  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.  Then this
can be handed to a stylesheet that would turn it into a link of some
sort.

Cluttering ddoc comments with URLs (or, as a proxy, macros containing
information specific to URLs) that, arguably, the code itself shouldn't
depend on, is something I have ideological issues with.  It's one thing
to refer to a full URL to some online reference like a technical spec
that's unchanging and, ostensibly, will always be out there; it's quite
something else to explicitly spell out links to a particular symbol
using a hard-coded path that can change any time.  E.g., today I may
link to MyType as:

	$(LINK $(WEBROOT)/mypackage/mymod.html#MyType)
	
but tomorrow I may have a major refactoring and now I have to change
*all* such links to:

	$(LINK $(WEBROOT)/mynewpackage/newsubpackage/newmod.html#MyType)

instead, whereas the code itself actually doesn't need to change at all,
because the compiler already knows where's the new location of the
symbol, using standard identifier resolution.

Why can't I just write `[MyType]` (or whatever other syntax you prefer),
and let the compiler figure out what the right fully-qualified name is?
Once the compiler figures it out, the stylesheet takes care of turning
it into a HTML link or the equivalent in whatever other output format
you may be using.

On a higher level, even explicit links to symbols in Phobos docs are a
bad idea.  What if 5 months later we decide to move dlang.org/phobos to
dlang.org/docs/phobos?  Or if a Phobos refactoring moves a symbol to
another module?  Any explicit URLs in user ddoc comments will break, and
will have to be updated *one-by-one*.  Whereas if we let the compiler do
its job, the worst that would happen is we update the stylesheet to
point to dlang.org/docs/phobos/* instead of dlang.org/phobos/*, and
*all* links in generated ddocs will be automatically corrected. Any
change in the path to the symbol's doc will already have been resolved
by the compiler -- if your code compiles at all.

tl;dr: I think anything more than plain old markup saying "this is a
symbol that needs a link" in a doc comment is a bad idea.  Ddoc comments
shouldn't be replicating the job of the compiler, and that poorly.


T

-- 
If creativity is stifled by rigid discipline, then it is not true creativity.