Bug #12258
closedRDoc bug when handling comments in C code examples
Description
RDoc fails to correctly convert documentation that includes C example code with /* ... */
comments.
It does not only produce wrong output for the comment itself (stripping the /*
and */
), but also gets confused with occurences of *
in completely different parts of the documentation, so that e.g. lists are displayed as code blocks. It appears that *
at the very beginning of a line triggers a code block under these circumstances.
This affects e.g. http://docs.ruby-lang.org/en/trunk/extension_rdoc.html#label-Check+Data+Type+of+the+VALUE (partially stripped /*
and */
from code example) or http://docs.ruby-lang.org/en/2.2.0/README_EXT.html#label-Adding+New+Features+to+Ruby (list displayed as code block); note that the broken list is fixed in trunk (it's rather a workaround) by using "-" for the list items.
Minimal example for a pure rdoc page:
$ cat broken_page.rdoc
A list:
* item 1
* item 2
A sentence with *emphasis* directly at the
*start* of a line.
Some example C code with comment:
void
do_something(VALUE val)
{
/* comment */
}
For this rdoc produces:
A list:
item 1
item 2
A sentence with emphasis directly at the
start* of a line.
Some example C code with comment:
void
do_something(VALUE val)
{
comment
}
When generating rdoc of a Ruby class, the bug affects only the code example itself:
$ cat broken.rb
# A class with broken rdoc.
#
# A list:
#
# * item 1
# * item 2
#
# A sentence with *emphasis* directly at the
# *start* of a line.
#
# Some example C code with comment:
#
# void
# do_something(VALUE val)
# {
# /* comment */
# }
#
class Broken
end
This produces:
A class with broken rdoc.
A list:
- item 1
- item 2
A sentence with emphasis directly at the start of a line.
Some example C code with comment:
void
do_something(VALUE val)
{
comment
}
Updated by stomar (Marcus Stollsteimer) almost 8 years ago
Also opened an issue for RDoc: https://github.com/rdoc/rdoc/issues/402
Updated by hsbt (Hiroshi SHIBATA) almost 8 years ago
- Status changed from Open to Assigned
- Assignee set to hsbt (Hiroshi SHIBATA)
I will pick commits from upstream when it was fixed.
Updated by hsbt (Hiroshi SHIBATA) over 5 years ago
- Assignee changed from hsbt (Hiroshi SHIBATA) to aycabta (aycabta .)
Updated by jeremyevans0 (Jeremy Evans) over 3 years ago
- Status changed from Assigned to Closed