www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 3554] New: Ddoc generats invalid output for documentation comments with non paired paranthasis

reply d-bugmail puremagic.com writes:
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



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: -------
Nov 27 2009
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554


Johannes Pfau <johannespfau gmail.com> changed:

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



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: -------
Jul 25 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




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: -------
Jul 25 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




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: -------
Aug 17 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




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: -------
Aug 17 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
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



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: -------
Aug 17 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
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



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: -------
Aug 17 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554


Johannes Pfau <johannespfau gmail.com> changed:

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



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: -------
Sep 17 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




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: -------
Sep 20 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




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: -------
Sep 20 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




I may open a different bug report that asks for LPAREN and RPAREN macros to be
defined in dmd, to be sure this problem doesn't get lost.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Sep 20 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554


Jonathan M Davis <jmdavisProg gmx.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jmdavisProg gmx.com



PDT ---
They _are_ defined. They're $(LPAREN) and $(RPAREN).

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Sep 20 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554






 They _are_ defined. They're $(LPAREN) and $(RPAREN).


Then where is the bug? Because there is a problem still.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Sep 20 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




PDT ---
Sorry, I didn't read the bug report all the way through. A new warning relating
to unmatched parens in ddoc popped up with 2.049, and it specifically mentions
$(LPAREN) and $(RPAREN), indicating that they are defined (hence why I told you
that they are). But if they aren't working, then that would indicate that
they're supposed to be defined but aren't, and then a bug report should indeed
be filed.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Sep 20 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554


bearophile_hugs eml.cc changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |REOPENED
         Resolution|FIXED                       |



Reopened because the problem isn't solved yet. See Comment 8.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Sep 21 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




16:50:01 PST ---
Thanks for your hard work, but I just tested initial bugreport in DMD 2.050,
and it still do not work as expected.

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

  void main() { }


<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>
<dt><big>float <u>h</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>


No ( or ).   :(

When compiling with -wi, i got

ttt.d(2): Warning: Ddoc: Stray '('. This may cause incorrect Ddoc output. Use
$(LPAREN) instead for unpaired left parentheses.
ttt.d(4): Warning: Ddoc: Stray ')'. This may cause incorrect Ddoc output. Use
$(RPAREN) instead for unpaired right parentheses.

Why it is hard to detect non-macro usage of parantheses? I was thinking macros
need have $ before opening (. 


After creating ddoc file:
RPAREN = )
LPAREN = (

And compiling again, i had now:

<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>
<dt><big>float <u>h</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>


Which is exactly what was expected! (Warning are still there). But it works.

So just resolving problem with macro definition in compiler is needed.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Nov 21 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554


Walter Bright <bugzilla digitalmars.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|REOPENED                    |RESOLVED
         Resolution|                            |FIXED
            Summary|Ddoc generats invalid       |Ddoc generates invalid
                   |output for documentation    |output for documentation
                   |comments with non paired    |comments with non paired
                   |paranthasis                 |parantheses



11:29:44 PST ---
http://www.dsource.org/projects/dmd/changeset/788

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Dec 06 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




Just a note. This program, compiled with -w:


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


Prints:
test3.d(2): Warning: Ddoc: Stray ')'. This may cause incorrect Ddoc output. Use
$(RPAREN) instead for unpaired right parentheses.

But the generated HTML is correct.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Dec 21 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554


Don <clugdbug yahoo.com.au> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |clugdbug yahoo.com.au





 Just a note. This program, compiled with -w:
 
 
 /// Return a random number in [0, 10)
 void foo() {}
 void main() {}
 
 
 Prints:
 test3.d(2): Warning: Ddoc: Stray ')'. This may cause incorrect Ddoc output. Use
 $(RPAREN) instead for unpaired right parentheses.
 
 But the generated HTML is correct.


This behaviour is intentional. DDoc now inserts a $(RPAREN) for you, that's why
it's a warning, not an error.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Dec 21 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




PST ---
Short explanation of the warning:

Consider this comment:
/// Return a random number in $(BOLD [0, 10))

DMD cannot know if you mean:
/// Return a random number in $(BOLD [0, 10$(RPAREN))
(right parenthesis is bold)

or
/// Return a random number in $(BOLD [0, 10)$(RPAREN)
(right parenthesis isn't bold)

So in some cases it could cause wrong output and therefore the warning is
needed.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Dec 21 2010
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3554




09:25:02 PST ---


 Short explanation of the warning:
 
 Consider this comment:
 /// Return a random number in $(BOLD [0, 10))
 
 DMD cannot know if you mean:
 /// Return a random number in $(BOLD [0, 10$(RPAREN))
 (right parenthesis is bold)
 
 or
 /// Return a random number in $(BOLD [0, 10)$(RPAREN)
 (right parenthesis isn't bold)
 
 So in some cases it could cause wrong output and therefore the warning is
 needed.


Yes and no.

It is not needed in case of our initial reports.

  /// Return a random number in [0, 10)

As "[0,10)"  is not in any macro, there is only one possible interpretation. Or
it is in some implicit macro?

So warning isn't needed in this situations probably. But warning is acceptable
IMHO for now. Thanks.

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