Bug #9366 :: Last line with comment in <code> disappears

Package home | Report new bug | New search | Development Roadmap

Status: Open | Feedback | All | Closed Since Version 1.5.0a1

Bug #9366	Last line with comment in <code> disappears
Submitted:	2006-11-17 18:25 UTC
From:	anode at goo dot cz	Assigned:	ashnazg
Status:	Closed	Package:	PhpDocumentor (version 1.3.1)
PHP Version:	5.1.6	OS:	Windows XP
Roadmaps:	1.3.2
Subscription	Your email:

Comments Add Comment Add patch

[2006-11-17 18:25 UTC] anode at goo dot cz (Ondrej Bouda)

Description:
------------
In HTML output, in a DocBlock inside  block, the last line of code which ends with a comment disappears. All the previous lines are OK. If there is no comment at the last line, it's printed correctly (although indented one space right).
Ran the following test script with command:
phpdoc -f phpdoc.php -t docs -o "HTML:Smarty:PHP"
which didn't report any errors or warnings.

Test script:
---------------

 * this_line_works(); // even with a comment
 * this_one_doesnt(); // because of this comment
 * 
 * @package     BugReport
 */
class Wheee {}
?>

Expected result:
----------------
 this_line_works(); // even with a comment
  this_one_doesnt(); // because of this comment

Actual result: --------------

this_line_works(); // even with a comment

Comments

[2006-11-29 18:46 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

Tried it with three lines in the <code> block.  The second line does appear, third line does not.  However, the second line is indented once space, like anode described, but the comments on each code line don't seem to be the culprit since all three of my lines have a comment:

 * <code>
 * this_line_works(); // even with a comment
 * does_this_one_work(); // yes, but indented one space
 * this_one_doesnt(); // because of this comment
 * </code>

[2006-11-29 18:56 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

More fun...

I removed the comment from the first and third lines, leaving only the second line with a comment.  In the output, the first line appears ok, the second line appears ok (NOT indented), and the third line appears but IS indented.

I then added two more lines, so that only the 2nd and 4th had comments.  In the output, all five lines appear, but only the 3rd and 5th are indented.

I then removed all but the 1st line, and put a comment on it.  In the output, it was missing.

OBSERVATIONS:
- any occurrence of a comment will cause only the very next line to be indented one space.
- a comment on the last line will cause it to be missing.
- the Converter is irrelevant.

[2006-11-29 19:56 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

Looking deeper at the tutorial documentation where <code> examples are shown, I noticed that they usually included the PHP start and end tags inside the <code> block.  When I add them, I still get an indention after a commented line, but the last line is no longer missing when it has a comment.

So, unless you include the PHP start/end tags in your code block, then the parser treats it like it's HTML code, and NOT like it's PHP code.  I tested this thought by removing the PHP tags, then rewriting the comments using the "<-- comment -->" syntax for HTML comments instead of the "// comment" syntax for PHP comments... all five comment lines appeared ok in the output.

I carried that thought further by only surrounding the comments themselves with PHP start/end tags, and that output looks absolutely perfect... all five lines appeared ok, with no extraneous indentions.  Granted, this meant that only the comments themselves were syntax-highlighted.

Even further... I surrounded each individual line with each's own PHP start/end tags.  Those results were perfect also.

The bottom line?  If it's PHP code you're showing, you need to include the PHP start/end tags in the code block... otherwise the code won't be parsed/highlighted as PHP, it'll be parsed as HTML.

However, I still can't explain away why the line immediately following a PHP comment is ALWAYS indented one space...  manipulating the PHP tags did NOT solve that oddity.

[2006-11-29 21:51 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

After further reading of the tutorial docs regarding use of the <code> construct, I'm not completely convinced that my earlier assertion of "surround your PHP code with PHP tags" is an _intentional_ necessity.  Of the many uses of the <code> construct I'm seeing in the tutorials and in phpDoc's own unit tests, I don't think such a PHP tag was intended by Greg/Josh to be required... I think the code is just coincidentally behaving that way.

This appears to be a legit bug, at least for the indention problem, but I _feel_ like PHP tag issue may also be another bug.

[2006-11-29 22:00 UTC] cellog (Greg Beaver)

The bug is in phpDocumentor/HighlightParser.inc.  Concentrate your investigations there.  What is probably happening is that the parser is not kicking out of the last state and flushing the comment, as one-line comments need a "\n" to terminate.  I thought I had fixed this.  To prove me correct, try this code:

/**
 * hi
 *
 * <code>
 * $line1 = 2; // line 1
 * $line2 = 2; // line 2
 * $line3 = 3; // line 3
 * ;
 * </code>
 */

[2006-12-01 22:45 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

Greg, your example does indeed correctly display the third line and its comment, as well as displaying the standalone semicolon line.

On your advice, I've been digging my way through HighlightParser.inc.  Not intimately knowing the code, I've really just been adding "debug" prints in all the methods that are being triggered as I spot them being executed... all the while looking for some pattern of behavior.  In short, I'm trying to learn the code, but it's a slow dig.

However, I have a question that might possibly lead YOU directly to a solution.  The description of the handleDocBlock method in the phpDocumentor_HighlightParser class indicates it knows to call the handleComment method when it realizes it's dealing with a plain "comment" rather than a "docblock".  However, I see nowhere in handleDocBlock where handleComment is being called.  Do you think you can take a look and see (with your knowledge of the code) if that is exactly the culprit here?

[2006-12-05 15:54 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

I'm still adding debug statements to methods, still trying to digest the worfklow as well as look for behavior patterns to help illuminate the problem.

On the issue of the extra space on each following line, behavior suggests to me that ANY comment line will result in the following line getting a leading space.  I tried a block like this:
 * <code>
 * // line 0
 * $line1 = 1; // line 1
 * $line2 = 2; // line 2
 * </code>

and the result had the $line1 line indented as well as the expected $line2 indention.  So, it looks like the extra space is solely due to an immediately preceding comment line.

I'm making less progress understanding the main problem of phpdoc not generating the last line of the <code> block.  However, seeing two PHP Notice errors in the generation output does lean me toward my original suspicion of an off-by-one type problem (my line numbers don't match CVS version of file, due to my added debug lines):

Notice: Undefined offset:  3 in c:\HighlightParser.inc on line 92 ($token = $this->_all[$linenum][$pos];)

Notice: Undefined index:   in c:\HighlightParser.inc on line 437 ($tok = $this->_wp->_all[$tok1[0]][$tok1[1]];)

[2006-12-05 17:09 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

More on the indention...

It now seems to me that a comment ALWAYS results in a trailing space on the following line, while a code line always causes its own leading space.  One comment line leading a second comment line does NOT cause the second line to indent.

Perhaps that trailing space caused by the comment line should instead be suppressed?  I don't see a trailing space being caused by a code line.  Or, perhaps that trailing space THINKS it is being placed at the beginning of the comment line itself?  If the comment line doesn't actually realize it is on the same line as its code line, it may be trying to place its own leading space before placing itself in the output line... maybe the comment itself is being placed on the correct line but the leading space it not?

[2006-12-05 18:16 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

Good grief, Chuck, get with it...

Those PHP Notices should be enough to tell me that some function call that should RESULT in outputting the last line is ITSELF failing, and therefore is not FINISHING its work of getting said line into the output.  No more mysterious than that.

I'll see what I can figure out regarding those offset/index notices...

[2006-12-06 16:34 UTC] ashnazg at users dot sourceforge dot net (Chuck Burgess)

Interestingly, the same indention problem (though not the missing line problem) occur when the filesource tag causes the entire source file to be parsed/converted.  I made the class piece look like this:

class Whee {
   $line1 = 1; // line 1
   $line2 = 2; // line2
}

and the resulting filesource page shows line2 ok in the class block but indented THREE spaces...