On Fri, Feb 02, 2018 at 10:49:18AM -0700, Jonathan M Davis via Digitalmars-d 
> 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

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.


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

Reply via email to