⚝
One Hat Cyber Team
⚝
Your IP:
216.73.216.133
Server IP:
185.119.109.197
Server:
Linux managedhosting.chostar.me 5.15.0-160-generic #170-Ubuntu SMP Wed Oct 1 10:06:56 UTC 2025 x86_64
Server Software:
Apache
PHP Version:
8.1.33
Buat File
|
Buat Folder
Eksekusi
Dir :
~
/
usr
/
share
/
ri
/
3.0.0
/
system
/
View File Name :
page-method_documentation_rdoc.ri
U:RDoc::TopLevel[ i I" method_documentation.rdoc:EFcRDoc::Parser::Simpleo:RDoc::Markup::Document: @parts[aS:RDoc::Markup::Heading: leveli: textI" Method Documentation Guide;To: RDoc::Markup::BlankLine o: RDoc::Markup::Paragraph;[I"PThis guide discusses recommendations for documenting methods for Ruby core ;TI"1classes and classes in the standard library.;T@ S; ; i; I" Goal;T@ o; ;[ I"HThe goal when documenting a method is to impart the most important ;TI"Iinformation about the method in the least amount of time. A reader ;TI"Fof the method documentation should be able to quickly understand ;TI"Hthe purpose of the method and how to use it. Providing too little ;TI"Iinformation about the method is not good, but providing unimportant ;TI"Ginformation or unnecessary examples is not good either. Use your ;TI"Ijudgment about what the user of the method needs to know to use the ;TI"method correctly.;T@ S; ; i; I"General Structure;T@ o; ;[I"AThe general structure of the method documentation should be:;T@ o:RDoc::Markup::List: @type: BULLET: @items[ o:RDoc::Markup::ListItem: @label0;[o; ;[I"(call-seq (for methods written in C);To;;0;[o; ;[I"!Synopsis (Short Description);To;;0;[o; ;[I"Details and Examples;To;;0;[o; ;[I"(Argument Description (if necessary);To;;0;[o; ;[I" Corner Cases and Exceptions;To;;0;[o; ;[I" Aliases;To;;0;[o; ;[I" Related Methods (optional);T@ S; ; i; I"(call-seq (for methods written in C);T@ o; ;[I"DFor methods written in C, RDoc cannot determine what arguments ;TI"@the method accepts, so those need to be documented using a ;TI"=<tt>call-seq</tt>. Here's an example <tt>call-seq</tt>:;T@ o:RDoc::Markup::Verbatim;[ I"* call-seq: ;TI"!* array.count -> integer ;TI"&* array.count(obj) -> integer ;TI"2* array.count {|element| ... } -> integer ;T: @format0o; ;[I"6When creating the <tt>call-seq</tt>, use the form;T@ o;;[I"Mreceiver_type.method_name(arguments) {|block_arguments|} -> return_type ;T;0o; ;[I"POmit the parentheses for cases where the method does not accept arguments, ;TI"@and omit the block for cases where a block is not accepted.;T@ o; ;[I"QIn the cases where method can return multiple different types, separate the ;TI"Ptypes with "or". If the method can return any type, use "object". If the ;TI"-method returns the receiver, use "self".;T@ o; ;[ I"SIn cases where the method accepts optional arguments, use a <tt>call-seq</tt> ;TI"Twith an optional argument if the method has the same behavior when an argument ;TI"Uis omitted as when the argument is passed with the default value. For example, ;TI" use:;T@ o;;[I"G* obj.respond_to?(symbol, include_all=false) -> true or false ;T;0o; ;[I"Instead of:;T@ o;;[I"4* obj.respond_to?(symbol) -> true or false ;TI"A* obj.respond_to?(symbol, include_all) -> true or false ;T;0o; ;[I"QHowever, as shown above for <tt>Array#count</tt>, use separate lines if the ;TI"6behavior is different if the argument is omitted.;T@ o; ;[I"$Omit aliases from the call-seq.;T@ S; ; i; I" Synopsis;T@ o; ;[ I"EThe synopsis comes next, and is a short description of what the ;TI"Bmethod does and why you would want to use it. Ideally, this ;TI"Gis a single sentence, but for more complex methods it may require ;TI"an entire paragraph.;T@ o; ;[I"/For <tt>Array#count</tt>, the synopsis is:;T@ o;;[I",Returns a count of specified elements. ;T;0o; ;[I"FThis is great as it is short and descriptive. Avoid documenting ;TI"Gtoo much in the synopsis, stick to the most important information ;TI"#for the benefit of the reader.;T@ S; ; i; I"Details and Examples;T@ o; ;[ I"HMost non-trivial methods benefit from examples, as well as details ;TI"Hbeyond what is given in the synopsis. In the details and examples ;TI"Fsection, you can document how the method handles different types ;TI"Cof arguments, and provides examples on proper usage. In this ;TI"Fsection, focus on how to use the method properly, not on how the ;TI"7method handles improper arguments or corner cases.;T@ o; ;[ I"HNot every behavior of a method requires an example. If the method ;TI"Jis documented to return +self+, you don't need to provide an example ;TI"Jshowing the return value is the same as the receiver. If the method ;TI"Iis documented to return +nil+, you don't need to provide an example ;TI"Gshowing that it returns +nil+. If the details mention that for a ;TI"Gcertain argument type, an empty array is returned, you don't need ;TI"$to provide an example for that.;T@ o; ;[ I"IOnly add an example if it provides the user additional information, ;TI"Edo not add an example if it provides the same information given ;TI"Jin the synopsis or details. The purpose of examples is not to prove ;TI""what the details are stating.;T@ S; ; i; I"(Argument Description (if necessary);T@ o; ;[ I"KFor methods that require arguments, if not obvious and not explicitly ;TI"Kmentioned in the details or implicitly shown in the examples, you can ;TI"Nprovide details about the types of arguments supported. When discussing ;TI"Lthe types of arguments, use simple language even if less-precise, such ;TI"Nas "level must be an integer", not "level must be an Integer-convertible ;TI"Oobject". The vast majority of use will be with the expected type, not an ;TI"Gargument that is explicitly convertible to the expected type, and ;TI"1documenting the difference is not important.;T@ o; ;[I"LFor methods that take blocks, it can be useful to document the type of ;TI"Kargument passed if it is not obvious, not explicitly mentioned in the ;TI"7details, and not implicitly shown in the examples.;T@ o; ;[I"GIf there is more than one argument or block argument, use an RDoc ;TI"definition list:;T@ o;;: NOTE;[o;;[I"argument_name1 ;T;[o; ;[I"type and description;To;;[I"argument_name2 ;T;[o; ;[I"type and description;T@ S; ; i; I" Corner Cases and Exceptions;T@ o; ;[I"JFor corner cases of methods, such as atypical usage, briefly mention ;TI"3the behavior, but do not provide any examples.;T@ o; ;[ I"LOnly document exceptions raised if they are not obvious. For example, ;TI"Jif you have stated earlier than an argument type must be an integer, ;TI"Myou do not need to document that a TypeError is raised if a non-integer ;TI"Kis passed. Do not provide examples of exceptions being raised unless ;TI"@that is a common case, such as Hash#fetch raising KeyError.;T@ S; ; i; I" Aliases;T@ o; ;[I"PMention aliases in the form "Array#find_index is an alias for Array#index.";T@ S; ; i; I" Related Methods (optional);T@ o; ;[I"JIn some cases, it is useful to document which methods are related to ;TI"Gthe current method. For example, documentation for Hash#[] might ;TI"Jmention Hash#fetch as a related method, and Hash#merge might mention ;TI"I#merge! as a related method. Consider which methods may be related ;TI"Jto the current method, and if you think the reader would benefit it, ;TI"Fat the end of the method documentation, add a line starting with ;TI"G"Related: " (e.g. "Related: #fetch"). Don't list more than three ;TI"Hrelated methods. If you think more than three methods are related, ;TI"Fpick the three you think are most important and list those three.;T@ S; ; i; I".Methods Accepting Multiple Argument Types;T@ o; ;[I"KFor methods that accept multiple argument types, in some cases it can ;TI"Jbe useful to document the different argument types separately. It's ;TI"Gbest to use a separate paragraph for each case you are discussing.;T@ S; ; i; I"Use of English;T@ o; ;[I"JReaders of this documentation may not be native speakers of English. ;TI"7Documentation should be written with this in mind.;T@ o; ;[I"LUse short sentences and group them into paragraphs that cover a single ;TI"Ktopic. Avoid complex verb tenses, excessive comma-separated phrases, ;TI"and idioms.;T@ o; ;[ I"HWhen writing documentation, define unusual or critical concepts in ;TI"Hsimple language. Provide links to authoritative sources, or add a ;TI"Igeneral description to the top-level documentation for the class or ;TI" module.;T@ S; ; i; I"Formatting;T@ o; ;[ I"KExtraneous formatting such as headings and horizontal lines should be ;TI"Iavoided in general. It is best to keep the formatting as simple as ;TI"Lpossible. Only use headings and other formatting for the most complex ;TI"Mcases where the method documentation is very long due to the complexity ;TI"of the method.;T@ o; ;[I"8Methods are documented using RDoc syntax. See the ;TI"~{RDoc Markup Reference}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-RDoc+Markup+Reference] ;TI"9for more information on formatting with RDoc syntax.;T: @file@:0@omit_headings_from_table_of_contents_below0