On Tuesday, December 12, 2017 16:12:50 Adam D. Ruppe via Digitalmars-d wrote: > On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis > > wrote: > > Personally, I would _very_ much like to see the magic > > formatting in ddoc kept to a minimum. > > You know what drives me nuts? This* is weird. > > * it is rendered as a list item! And I know, you can do \*. But > ugh. > > Ugh. Or why is _this_ italic? > > > But those, while enough to bring my hatred, are not why I did > something new for adrdox... it is the missed opportunities for > links. adrdox links are more inspired by the wikipedia link > syntax and uses knowledge of D to keep them very concise: > > /// Does something. See also: [bar]. > void foo(); > > /// Does something similar. See also: [foo]. > void bar(); > > > When it sees a string in brackets, it does a name lookup > following D's scoping rules for that declaration, and creates a > link to it. It even understands imports (slightly buggy but i'll > fix that eventually): > > import std.stdio; > import arsd.color; > > /// calls [writeln] on the given [Color|color]. > void bar(Color s, string txt); > > > > You also see the pipe syntax there which replaces the text for > the link. It always does [link_to|displayed_text] where > displayed_text = link_to if it is not present. In markdown, i > often reverse these. > > > But anyway, I struggled a bit on using single brackets for this, > since I hate magic syntax too... but I went with it because > cross-linking like this is VERY common and adds a lot to the > documentation. I use it very frequently (in the docs I've written > with the new generator; many of mine are still in the transition > period from ddoc). In fact, I use it almost as frequently as > `code` (which doesn't attempt namespace lookups because it is too > generic and linking in there leads to silly results). > > > Phobos' $(REF) macro tries to do something similar but it is a > huge pain since it needs more qualification; it doesn't look > stuff up in the actual D. > > Cross linking in documentation I find is a huge win in legibility > for the coder and readability for the end user. *this* vs $(B > this)? meh whatever.
Yeah. Unfortunately, given that ddoc is designed to be only a macro language and tries to not focus on html generation specifically, I don't know how feasible it is to make it deal with links properly while still working with other target formats. On some level ddoc's flexibility undermines it as a good tool for generating documentation. But for most of us, if ddoc could be improved to actually generate cross-links by default where appropriate (e.g. parameter types to the documentation for those types) and have built-in macros for manually generating cross-links within the documentation, then that would be a huge step up. As it stands, I think that in most cases, using something like ddox or adrdox works a lot better than using ddoc for everything, which is kind of sad given that the whole point of ddoc was to have something built-in for easily generating documentation. Maybe at some point, I'll look at seeing how reasonable it is to improve ddoc to deal with the links properly, but I'm not very familiar with the compiler, and I have too many projects as it is. - Jonathan M Davis
