diff --git a/doc/documentation_guide.rdoc b/doc/documentation_guide.rdoc index ff1bb88565..f93203d4f3 100644 --- a/doc/documentation_guide.rdoc +++ b/doc/documentation_guide.rdoc @@ -33,6 +33,62 @@ Use your judgment about what the user needs to know. consider a {list}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Simple+Lists]. - Idioms and culture-specific references. - Overuse of headers. + - Using US-ASCII-incompatible characters in C source files; + see {Characters}[#label-Characters] below. + +=== Characters + +Use only US-ASCII-compatible characters in a C source file. +(If you use other characters, the Ruby CI will gently let you know.) + +If want to put ASCII-incompatible characters into the documentation +for a C-coded class, module, or method, there are workarounds +involving new files doc/*.rdoc: + +- For class +Foo+ (defined in file foo.c), + create file doc/foo.rdoc, declare class Foo; end, + and place the class documentation above that declaration: + + # :markup: ruby + # Documentation for class Foo goes here. + class Foo; end + +- Similarly, for module +Bar+ (defined in file bar.c, + create file doc/bar.rdoc, declare module Bar; end, + and place the module documentation above that declaration: + + # :markup: ruby + # Documentation for module Bar goes here. + module Bar; end + +- For an instance method Baz#bat (defined in file baz.c), + create file doc/baz.rdoc, declare class +Baz+ + and instance method +bat+, and place the method documentation above + the method declaration: + + # :markup: ruby + class Baz + # Documentation for method bat goes here. + # (Don't forget the call-seq.) + def bat; end + end + +- For a singleton method Bam.bah (defined in file bam.c), + create file doc/bam.rdoc, declare class +Bam+ + and singleton method +bah+, and place the method documentation above + the method declaration: + + # :markup: ruby + class Bam + # Documentation for method bah goes here. + # (Don't forget the call-seq.) + def self.bah; end + end + + See these examples: + + - https://raw.githubusercontent.com/ruby/ruby/master/doc/string.rdoc + - https://raw.githubusercontent.com/ruby/ruby/master/doc/transcode.rdoc === \RDoc