Project

General

Profile

Actions
Copy link

Bug #12258

closed

RDoc bug when handling comments in C code examples

Added by stomar (Marcus Stollsteimer) about 8 years ago. Updated over 3 years ago.

Status:
Closed
Assignee:
aycabta (aycabta .)
Target version:
-
ruby -v:
ruby 2.3.0p0 (2015-12-25 revision 53290) [i686-linux]
Backport:
2.1: UNKNOWN, 2.2: UNKNOWN, 2.3: UNKNOWN
[ruby-core:74843]
Tags:
lib

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   
}
Actions
Copy link

Also available in: Atom PDF

Like0
Like0Like0Like0Like0