diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2022-03-11 10:46:47 -0600 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-03-11 10:46:47 -0600 |
commit | 09186f381f3ddadd6b9ffcd770255fe3bf175257 (patch) | |
tree | 9ec010b552c1cd773960f4f0189791e96be280b1 | |
parent | 95a85b6d31e8eab26ccc20e5300575e89e429f1d (diff) | |
download | ruby-09186f381f3ddadd6b9ffcd770255fe3bf175257.tar.gz |
Adding guidance about characters in C-code doc (#5641)
Showing how to do as @nobu does -- putting doc into doc/*.rdoc instead of in *.c.
-rw-r--r-- | doc/documentation_guide.rdoc | 56 |
1 files changed, 56 insertions, 0 deletions
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 <tt>doc/*.rdoc</tt>: + +- For class +Foo+ (defined in file <tt>foo.c</tt>), + create file <tt>doc/foo.rdoc</tt>, declare <tt>class Foo; end</tt>, + 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 <tt>bar.c</tt>, + create file <tt>doc/bar.rdoc</tt>, declare <tt>module Bar; end</tt>, + 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 <tt>baz.c</tt>), + create file <tt>doc/baz.rdoc</tt>, 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 <tt>bam.c</tt>), + create file <tt>doc/bam.rdoc</tt>, 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 |