[ruby-core:75074] [Ruby trunk Bug#12258] RDoc bug when handling comments in C code examples

Issue #12258 has been updated by Marcus Stollsteimer.


Also opened an issue for RDoc: https://github.com/rdoc/rdoc/issues/402

----------------------------------------
Bug #12258: RDoc bug when handling comments in C code examples
https://bugs.ruby-lang.org/issues/12258#change-58198

* Author: Marcus Stollsteimer
* Status: Open
* Priority: Normal
* Assignee: 
* ruby -v: ruby 2.3.0p0 (2015-12-25 revision 53290) [i686-linux]
* Backport: 2.1: UNKNOWN, 2.2: UNKNOWN, 2.3: UNKNOWN
----------------------------------------
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   
}
```




-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:[e-mail]?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>