Thread overview | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
November 27, 2009 [Issue 3554] New: Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
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: ------- |
July 25, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
July 25, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
August 17, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
August 17, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
August 17, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
August 17, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
September 17, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
September 20, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
September 20, 2010 [Issue 3554] Ddoc generats invalid output for documentation comments with non paired paranthasis | ||||
---|---|---|---|---|
| ||||
Posted in reply to Witold Baryluk | 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: ------- |
Copyright © 1999-2021 by the D Language Foundation