From: shibata.hiroshi@... Date: 2016-05-28T04:44:09+00:00 Subject: [ruby-core:75751] [Ruby trunk Bug#12258][Assigned] RDoc bug when handling comments in C code examples Issue #12258 has been updated by Hiroshi SHIBATA. Status changed from Open to Assigned Assignee set to Hiroshi SHIBATA I will pick commits from upstream when it was fixed. ---------------------------------------- Bug #12258: RDoc bug when handling comments in C code examples https://bugs.ruby-lang.org/issues/12258#change-58880 * Author: Marcus Stollsteimer * Status: Assigned * Priority: Normal * Assignee: Hiroshi SHIBATA * 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: