http://d.puremagic.com/issues/show_bug.cgi?id=3554

           Summary: Ddoc generats invalid output for documentation
                    comments with non paired paranthasis
           Product: D
           Version: 2.032
          Platform: Other
        OS/Version: Linux
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DMD
        AssignedTo: nobody@puremagic.com
        ReportedBy: baryluk@smp.if.uj.edu.pl


--- Comment #0 from Witold Baryluk <baryluk@smp.if.uj.edu.pl> 2009-11-27 08:07:12 PST ---
Both this code:

/** Produces something in (a;b] */
float f(float a, float b) { return (a+b)/2.0; }

produces:
=====
<br><br>
$(DDOC_MODULE_MEMBERS
<dt><big>float <u>f</u>(float <i>a</i>, float <i>b</i>);
</big></dt>
<dd>Produces something in (<i>a</i>;<i>b</i>]
)
<br><br>

</dd>
=====

and this:

/** Produces something in [a;b) */
float f(float a, float b) { return (a+b)/2.0; }


produces
=====
<br><br>
<dl><dt><big>float <u>f</u>(float <i>a</i>, float <i>b</i>);
</big></dt>
<dd>Produces something in [<i>a</i>;<i>b</i><br><br>

</dd>
</dl>
)
=====

Produces very broken HTML files.


It should be somthing like:
======
<br><br>
<dl><dt><big>float <u>f</u>(float <i>a</i>, float <i>b</i>);
</big></dt>
<dd>Produces something in [<i>a</i>;<i>b</i>)
<br><br>

</dd>
</dl>

======

Of course i can use HTML entities, or other tricks, but this breaks assumption that ddoc comments should be both readble in code and in HTML.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554


Johannes Pfau <johannespfau@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |johannespfau@gmail.com


--- Comment #1 from Johannes Pfau <johannespfau@gmail.com> 2010-07-25 01:04:43 PDT ---
This requires dmd to escape parenthesis in the doc comments.

It seems like in doc.c, Section::write is the place to look at. There's already an loop in that function replacing _ with spaces. That could be extended to also replace ( and ) with some escape sequence. Maybe something like \( and \) and the escape character then needs to be escaped [\\] as well. However, this could get a little complicated, because sections can call macros and those macro calls should get escaped.

Then in macro.c the code scanning for parenthesis must be aware of this
escaping.
I think this would mean adding a case for the escape character to the switch
block in extractArgN and skipping over the escape sequence.

The last step is to remove the escape characters in doc.c, Module::gendocfile. There's already code to do that for the 0xFF escape character. That could either be extended for another escape character, or we could just use 0xFF as the escape sequence.

Maybe the best solution is to just escape parenthesis manually in the source file. I don't know if this is possible though, and it's definitely not documented.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554



--- Comment #2 from Johannes Pfau <johannespfau@gmail.com> 2010-07-25 01:12:17 PDT ---
I meant those macro calls should _not_ get escaped, sorry.

Also, some more work would be needed to protect against parenthesis in section names. But I guess this is usually not a problem.

Example:
/**
 * Test):
 **/
float f(float a, float b) { return (a+b)/2.0; }

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554



--- Comment #3 from Johannes Pfau <johannespfau@gmail.com> 2010-08-17 03:37:48 PDT ---
Created an attachment (id=720)
proposed patch

This patch fixes all occurrences of stray parenthesis which could be produced by the user. This includes comment section bodies and headers. Basically with this patch the user cannot break the ddoc output anymore. I emphasize 'user' because the compiler can still break it. std.random shows one of these examples: A function with an string default argument like this : = "(}". This will still break the documentation output, but that's another issue and I'll provide a fix for that soon.

What the path does is:
1. If there's a stray ( or ) in the comments, replace it with $(LPAREN ) /
$(RPAREN )
2. If the user has warnings enabled, emit a warning about the stray
parenthesis. The loc is set to the corresponding dsymbol location. More
detailed line information is not possible, because the parser does not pass
this info to the DocComment structure.

Note that automatically replacing the stray parenthesis is not the ultimate
solution, it just limits damage to the current section. For example:
"$(Test ) )" becomes  "$(Test ) $(LPAREN )" but you might want "$(Test $(LPAREN
) )". The compiler cannot know this. Therefore parenthesis should be escaped
manually if one needs stray parenthesis.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554



--- Comment #4 from Johannes Pfau <johannespfau@gmail.com> 2010-08-17 03:42:07 PDT ---
Created an attachment (id=721)
test case

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554


Johannes Pfau <johannespfau@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |patch
           Platform|Other                       |All
            Version|2.032                       |D1 & D2
         OS/Version|Linux                       |All


--- Comment #5 from Johannes Pfau <johannespfau@gmail.com> 2010-08-17 03:48:09 PDT ---
Almost forgot:
The patch is against dmd 2.048 but it should be trivial to adopt to D1.
The warnings look like this:

test.d(64): Warning: Ddoc: Stray ')'. This may cause incorrect ddoc output. Use
$(RPAREN ) instead for unpaired parenthesis. See
http://url-with-explanation.com for more information.
test.d(69): Warning: Ddoc: 11 unclosed parenthesis. This may cause incorrect
ddoc output. Use $(LPAREN ) instead for unpaired parenthesis. See
http://url-with-explanation.com for more information.

Obviously the "http://url-with-explanation.com" should be replaced with an url
with an detailed description of this problem.
And one more thing: The patch corrects only 1024 stray parenthesis per section.
I think that should be enough, though.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554


Walter Bright <bugzilla@digitalmars.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
                 CC|                            |bugzilla@digitalmars.com
         Resolution|                            |FIXED


--- Comment #6 from Walter Bright <bugzilla@digitalmars.com> 2010-08-17 15:21:38 PDT ---
http://www.dsource.org/projects/dmd/changeset/620

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554


Johannes Pfau <johannespfau@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |bearophile_hugs@eml.cc


--- Comment #7 from Johannes Pfau <johannespfau@gmail.com> 2010-09-17 07:11:40 PDT ---
*** Issue 3957 has been marked as a duplicate of this issue. ***

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554



--- Comment #8 from bearophile_hugs@eml.cc 2010-09-20 05:03:38 PDT ---
This bug doesn't seem fixed in dmd 2.049. This program:


/// Return a random number in [0, 10 $(LPAREN)
void foo() {}
void main() {}



Generates an html that doesn't show the closing left parenthesis:


...
<dd>Return a random number in [0, 10 <br><br>

</dd>
...

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3554



--- Comment #9 from Johannes Pfau <johannespfau@gmail.com> 2010-09-20 07:28:22 PDT ---
Yeah, I also brought this up on the dmd-internals mailing list recently. The
problem is that the patch replaces the parenthesis with LPAREN and RPAREN
macros. Dmd should define these by default but it doesn't. Not defined ddoc
macros expand to an empty string. A workaround is to define these macros in an
ddoc file passed to dmd or in the macro section of a source file; the
definitions should look like this:
RPAREN = )
LPAREN = (

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------