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.