mirror of
https://github.com/onkelbeh/cheatsheets.git
synced 2026-09-09 22:49:38 +02:00
Nick-Builds-tools
9ceae55055
## Summary - keep the RDoc cheatsheet focused on RDoc markup and directives - move YARD-specific tags into a dedicated YARD cheatsheet - update both references against current official documentation ## Why The existing RDoc sheet mixes RDoc directives with YARD tags such as `@param`, `@return`, `@raise`, and `@option`. This makes the examples look like native RDoc syntax. The new split keeps each reference accurate and easier to scan. Closes #2176. Closes #2172. ## Checks - Prettier passes for both Markdown files - frontmatter and fenced code blocks verified - no promotional links or unrelated changes
142 lines
2.9 KiB
Markdown
142 lines
2.9 KiB
Markdown
---
|
|
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<String>]` | 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}
|
|
|
|
- <https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md>
|
|
- <https://www.rubydoc.info/gems/yard/file/docs/Tags.md>
|
|
- <https://yardoc.org/types.html>
|
|
{: .-also-see}
|