Project

General

Profile

Bug #12258

RDoc bug when handling comments in C code examples

Added by stomar (Marcus Stollsteimer) over 2 years ago. Updated about 1 month ago.

Status:
Assigned
Priority:
Normal
Target version:
-
ruby -v:
ruby 2.3.0p0 (2015-12-25 revision 53290) [i686-linux]
[ruby-core:74843]

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   
}

History

#2 [ruby-core:75751] Updated by hsbt (Hiroshi SHIBATA) over 2 years ago

  • Assignee set to hsbt (Hiroshi SHIBATA)
  • Status changed from Open to Assigned

I will pick commits from upstream when it was fixed.

#3 [ruby-core:89731] Updated by hsbt (Hiroshi SHIBATA) about 1 month ago

  • Assignee changed from hsbt (Hiroshi SHIBATA) to aycabta (aycabta .)

Also available in: Atom PDF