Inline code in the docs - the correct way

[Jonathan M Davis]

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.

- Jonathan M Davis