[Issue 16068] New: DDoc sections have serious design issues

via Digitalmars-d-bugs digitalmars-d-bugs at puremagic.com
Tue May 24 07:22:15 PDT 2016


          Issue ID: 16068
           Summary: DDoc sections have serious design issues
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: normal
          Priority: P1
         Component: dmd
          Assignee: nobody at puremagic.com
          Reporter: leandro.lucarella at sociomantic.com

Created attachment 1598
  --> https://issues.dlang.org/attachment.cgi?id=1598&action=edit
DDoc output

I don't want to make a full rant about DDoc (although I think is to D what the
D preprocessor is to C/C++).

I found a very fundamental problem. According to how sections are parsed, you
can accidentally build new unintended sections just by formatting your

For example:
        The contains() function is more convenient for trivial lookup
        if (contains ("fubar", '!'))

This is a real example of text inside DDoc. This text produces the attached
output (basically "cases:" is interpreted as a new section).

I'm not sure this has a solution, is just the whole DDoc system seems too
broken by design, but if someone can think of any heuristics to make this more
sensible (maybe requiring sections to have an empty line before?), it would be
interesting to know.


More information about the Digitalmars-d-bugs mailing list