[Enh|Specs] Not compliant with macros argument text specs

[Geod24]

Specs says:

The argument text can contain nested parentheses, "" or '' strings, comments, or tags. If stray, unnested parentheses are used, they can be replaced with the entity ( for ( and ) for ).

There are however several problems with this definition: 1) I don't see how there could be an unmatched ')', as it would be interpreted as the end of the macro argument list. However there could be unmatched '('. I'm not sure how good it is to replace it with HTML entity though, but since we got $(LPAREN), not a big deal. 2) The 'or tags' apparently refers to XML <tag></tag> (the only other reference to the word 'tag' in this page refers to XML). So this requires quite a lot of complexity for such a small feature, which has a limited interest. 4) DMD isn't compliant with the definition. Based on my understanding of this spec, I came up with the following test:

Command : dmd -c -Dffoo.html test.d debug.ddoc debug.ddoc:

DDOC=$(BODY)
DDOC_SUMMARY=[SUMMARY $0]
DDOC_DESCRIPTION=[DESCRIPTION $0]

test.d:

/**
 * Module title
 *
 * $(B (Nested parenthesis))
 * $(B "Double quoted: )")
 * $(B 'Quoted: )')
 * $(B <!-- Commented: ) -->)
 * $(B <tagged>)</tagged>)
 * $(B (Hello)
 *
 */
module doc.test;

Expected output:

<!-- Generated by Ddoc from test.d -->
$(DDOC_SECTIONS [SUMMARY Module title
]
[DESCRIPTION <b>(Nested parenthesis)</b>
 <b>"Double quoted: )"</b>
 <b>'Quoted: )'</b>
 <b><!-- Commented: ) -->)
 <b><tagged>)</tagged></b>
 <b>&#40;Hello</b>
]

Actual output:

<!-- Generated by Ddoc from test.d -->
$(DDOC_SECTIONS [SUMMARY Module title
]
[DESCRIPTION <b>(Nested parenthesis)</b>
 <b>"Double quoted: </b>")
 <b>'Quoted: </b>')
 <b><!-- Commented: ) -->)
 <b><tagged></b></tagged>)
 (B (Hello)</b>

So as you can see DMD gets all but the nested parenthesis wrong (and almost get the HTML/XML comment right). I'm definitely going to do a specs issue / P.R. to remove tags, and will consider the others cases, as supporting string would lead to supporting escaping. I'd rather ask users to use $({L,R}PAREN) whenever needed.