diff --git a/rdoc.md b/rdoc.md index 9197c4e2..8dad3e2e 100644 --- a/rdoc.md +++ b/rdoc.md @@ -1,150 +1,148 @@ --- -title: Rdoc +title: RDoc category: Markup +intro: | + Quick reference for RDoc markup and directives. For YARD tags such as `@param`, see the YARD cheatsheet. --- -### Basic RDoc format +### Basic comment +{: .-prime} -```rb -# Foo. +```ruby +# Adds two numbers. # -# @example -# -# y -# g -# -# @param [String] param_name The xx and xx. -# -# @see https://example.com/ -# -# @return [true] if so +# Returns the sum. +def add(left, right) + left + right +end ``` -### Hash parameters +RDoc associates a comment with the Ruby object immediately below it. -```rb -# @param [Hash] opts the options to create a message with. -# @option opts [String] :subject The subject -# @option opts [String] :from ('nobody') From address -# @option opts [String] :to Recipient email -# @option opts [String] :body ('') The email's body -``` +### Inline markup -### Parameter types - -```rb -# @param (see User#initialize) -# @param [OptionParser] opts the option parser object -# @param [Array] args the arguments passed from input. This -# array will be modified. -# @param [Array] list the list of strings and symbols. -# @param [Hash] a hash with symbol keys and string values -# -# The options parsed out of the commandline. -# Default options are: -# :format => :dot -``` - -### Exceptions -```rb -# @raise [AccountBalanceError] if the account does not have -# sufficient funds to perform the transaction -``` - -### Inline - -```markdown +```text *bold* _emphasized_ +code+ ``` -```markdown -{ObjectName#method optional title} -{Class::CONSTANT My constant's title} -{#method_inside_current_namespace} -``` +### Links and references -```markdown +```text https://www.example.com/ -See Models::User@Examples -{Google}[https://google.com/] +RDoc::Markup +RDoc::Markup#convert +{Ruby documentation}[https://docs.ruby-lang.org/] ``` -### Skip +## Structure -```rb -def input # :nodoc: +### Headings + +```text += Page title +== Section +=== Subsection ``` -```rb -module MyModule # :nodoc: all +### Lists + +```text +* First item +* Second item + +1. First step +2. Second step ``` ### Definition lists -```rb -# == Definition lists -# -# list:: hi. -# +foo+:: parameterized +```text +name:: description ++option+:: option description ``` -```rb -# == Definition lists -# [foo] also -# [bar] like this +```text +[name] description +[other] another description ``` -### Return types +## Directives -```rb -# @return [String] -# @return [String, nil] the name +### Hide documentation + +```ruby +def internal_method # :nodoc: +end + +module InternalNamespace # :nodoc: all +end ``` -### Callseq +```ruby +# :stopdoc: +def hidden_method +end +# :startdoc: +``` -```rb +### Calling sequence + +```ruby # :call-seq: -# ARGF.readlines(sep=$/) -> array -# ARGF.readlines(limit) -> array -# ARGF.readlines(sep, limit) -> array -# -# ARGF.to_a(sep=$/) -> array -# ARGF.to_a(limit) -> array -# ARGF.to_a(sep, limit) -> array +# readlines(sep = $/) -> array +# readlines(limit) -> array +# readlines(sep, limit) -> array ``` +Use `:call-seq:` when the generated signature needs to show multiple forms or a return value. + +### Arguments and yields + +```ruby +# :args: source, destination = nil +# :yields: value +``` + +These directives override the arguments or yielded values reported by RDoc. + ### Category -```rb +```ruby # :category: Utilities +# +# Escapes HTML characters. +def escape_html(text) +end ``` -### Sections +`:category:` applies only to the next documented item. -```rb +### Section + +```ruby # :section: Expiry methods -# methods relating to expiring +# Methods for expiring records. +# Expires the record. def expire! -def expired? -... +end ``` -### Using tomdoc +`:section:` remains active until another section directive changes it. -```rb +### Markup format + +```ruby # :markup: TomDoc ``` -Place this at the beginning of the file. +Place the directive at the beginning of the file to select a supported input format. ## Also see {: .-one-column} -* -* -* +- +- {: .-also-see} diff --git a/yard.md b/yard.md new file mode 100644 index 00000000..3f087cba --- /dev/null +++ b/yard.md @@ -0,0 +1,141 @@ +--- +title: YARD +category: Markup +intro: | + Quick reference for YARD tags in Ruby documentation. +--- + +### Method documentation +{: .-prime} + +```ruby +# Downloads a page. +# +# @param url [String] the page URL +# @param directory [String] the output directory +# @return [String] the saved file path +# @raise [DownloadError] if the request fails +# @example Download into the default directory +# download("https://example.com/") +def download(url, directory: "pages") +end +``` + +YARD tags begin with `@` at the start of a comment line. + +## Parameters and return values + +### Parameters + +```ruby +# @param name [String] the user name +# @param count [Integer] the number of retries +# @param enabled [Boolean] whether retries are enabled +``` + +For keyword parameters, use `@param`. + +### Return values + +```ruby +# @return [String] the matching name +# @return [nil] if no match exists +``` + +Use multiple `@return` tags for distinct return cases. + +### Exceptions + +```ruby +# @raise [AccountBalanceError] if funds are insufficient +``` + +### Options hash + +```ruby +# @param opts [Hash] message options +# @option opts [String] :subject the subject +# @option opts [String] :from ("nobody") the sender +# @option opts [String] :to the recipient +# @option opts [String] :body ("") the message body +``` + +Use `@option` for keys inside an options hash, not for keyword parameters. + +## Types + +### Common forms + +| Form | Meaning | +| --- | --- | +| `[String]` | One type | +| `[String, nil]` | Alternative types | +| `[Array]` | Collection members | +| `[Hash{Symbol => String}]` | Key and value types | +| `[#read]` | Duck type | +| `[Boolean]` | `true` or `false` | +| `[void]` | Return value unused | + +YARD type declarations are conventions rather than Ruby runtime checks. + +### Reference tags + +```ruby +# @param user [String] the user name +# @param host [String] the host name +def clean(user, host) +end + +# @param (see #clean) +def activate(user, host) +end +``` + +`(see OBJECT)` copies matching tag data from another documented object. + +## Examples and links + +### Example + +```ruby +# @example Reverse a string +# "hello".reverse #=> "olleh" +``` + +The optional text after `@example` becomes the example title. + +### Object references + +```text +{User} +{User#name} +{User#name Display name} +``` + +### Common tags + +| Tag | Use | +| --- | --- | +| `@api` | API audience | +| `@author` | Author name | +| `@deprecated` | Replacement guidance | +| `@example` | Usage example | +| `@note` | Important note | +| `@option` | Options hash key | +| `@param` | Method parameter | +| `@private` | Private API | +| `@raise` | Raised exception | +| `@return` | Return value | +| `@see` | Related object or URL | +| `@since` | First release | +| `@todo` | Pending work | +| `@yieldparam` | Block parameter | +| `@yieldreturn` | Block return value | + +## Also see +{: .-one-column} + +- +- +- +{: .-also-see}