Am 31.12.2013 00:37, schrieb Walter Bright: > On 12/30/2013 3:13 PM, Sönke Ludwig wrote: >> Am 30.12.2013 23:13, schrieb Walter Bright: >>> On 12/30/2013 1:25 PM, Sönke Ludwig wrote: >>>> Identifiers in documentation comments that are function parameters or >>>> are names that are in scope at the associated declaration are >>>> emphasized >>>> in the output. >>>> >>>> So the same problem is already reality - you already have to go through >>>> the documentation to see if there are any mis-highlighted words. >>> >>> 1. having a bad idea is not justification for doing it again :-) >> >> Of course not, but my point was that the mistake has already been made, >> so we may as well make the best out of it... not really doing it again >> in that sense. >> >> But if the decision is that in fact this was a mistake, it should get >> removed and replaced by a proper solution sooner rather than later (it's >> not that bad to lose some highlighting and Phobos uses $(D ...) anyway, >> so just removing it wouldn't hurt much). > > Ddoc is very heavily used. I don't believe we can make such silent, > breaking changes. >
It's just word highlighting! Breaking changes in the language are one thing, but this kind of fix is a whole different category. Keeping it will only make the problem worse over time. If there is a reasonable deprecation path, that would be better, of course, but the current situation is the worst of all possibilities. > >> And in that regard I'd like to >> point to "D's goals for embedded documentation" >> <http://dlang.org/ddoc.htm>. I very much agree with them, but the >> current reality looks like the opposite - lots of macro-pseudo-HTML >> markup, very difficult to read unprocessed in many places. So something >> like using "#" or "()" to mark symbols + automatic cross referencing for >> marked symbols would be a *really* nice to have. > > I don't see any particular advantage to using (name) rather than $(REF > name), and some serious disadvantages with false positives like > func(param). Oops! A markup language should really strive to minimize > special syntax. (I'm often tripped up by false positives in the wacky > markup languages in Skype, Github, Reddit, etc., each of which feels > compelled to reinvent markup.) It's not "(name)", but "name()" or "name(param)", which is recognized as a function call. "#name" also forces recognition as an identifier, as well as "::name" in C++'s case. I agree that going overboard with special syntax is a bad idea, but symbols in a code documentation language is such a fundamental thing that it should surely be among the first things, if not *the* first thing, that deserves a concise syntax. Also, the official first four goals of DDOC are: > 1. It looks good as embedded documentation, not just after it is > extracted and processed. > 2. It's easy and natural to write, i.e. minimal reliance on <tags> and > other clumsy forms one would never see in a finished document. > 3. It does not repeat information that the compiler already knows from > parsing the code. > 4. It doesn't rely on embedded HTML, as such will impede extraction > and formatting for other purposes. Using $(XREF), $(TABLE $(TR $(TD ...))), $(LINK a b) $(D ...) and so on is nothing but markup. If we go that route, we could as well remove all syntax, except for the macros: $(SUMMARY ...) $(SECTION See_Also ... ) $(PARAMS $(PARAM x ...) $(PARAM y ...) ) $(SECTION Example $(CODEBLOCK ... ) ) But you added the syntax for a reason back then (readability ...and writability). And the same goes for the auto-detection of identifiers. I think the only problem is that the default would have been better off the other way around.