Confirmed that this bug exists in v1.3.1, using PHP v4.4.4 and v5.1.6, testing all the HTML:default and HTML:Smarty converters.

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>

When I remove the comment from the third line, it will appear in the output, but it too is indented one space along with the second line...

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.

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.

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.

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> */

cellog: Yes, that's exactly what I used to solve this issue (but doesn't look very nice). And I can say that it works ok.

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?

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]];)

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?

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...

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...

Eureka... tiny fix in HighlightParser.inc handleComment(). I'll submit a sourceforge patch as soon as I've satisfied myself (through testing phpdoc generation against known-to-me codebases) that the fix doesn't break anything.

Submitted patch to sourceforge: https://sourceforge.net/tracker/index.php?func=detail&aid=1611847&group_id=11194&atid=311194

Thank you! Just tested with my scripts and everything works fine. Should I mark this bug as closed?

Probably not... need to wait to see if Greg or Josh choose to either commit the patch to CVS or fix it a different way.

I've committed sourceforge patch #1611847 to CVS... marking this bug as closed.

The patch is now available at sourceforge with the same item number, but it's listed under "bugs": https://sourceforge.net/tracker/index.php?func=detail&aid=1611847&group_id=11194&atid=111194