fix: separate RDoc and YARD references (#2232)

## 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

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
+```ruby
-# Foo.
+# Adds two numbers.
 #
-# @example
+# Returns the sum.
-#
+def add(left, right)
-#   y
+  left + right
-#   g
+end
-#
-# @param [String] param_name The xx and xx.
-#
-# @see https://example.com/
-#
-# @return [true] if so
 ```
 
-### Hash parameters
+RDoc associates a comment with the Ruby object immediately below it.
 
-```rb
+### Inline markup
-# @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
-```
 
-### Parameter types
+```text
-
-```rb
-# @param (see User#initialize)
-# @param [OptionParser] opts the option parser object
-# @param [Array<String>] args the arguments passed from input. This
-#   array will be modified.
-# @param [Array<String, Symbol>] list the list of strings and symbols.
-# @param [Hash<Symbol, String>] 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
 *bold*
 _emphasized_
 +code+
 ```
 
-```markdown
+### Links and references
-{ObjectName#method optional title}
-{Class::CONSTANT My constant's title}
-{#method_inside_current_namespace}
-```
 
-```markdown
+```text
 https://www.example.com/
-See Models::User@Examples
+RDoc::Markup
-{Google}[https://google.com/]
+RDoc::Markup#convert
+{Ruby documentation}[https://docs.ruby-lang.org/]
 ```
 
-### Skip
+## Structure
 
-```rb
+### Headings
-def input # :nodoc:
+
+```text
+= Page title
+== Section
+=== Subsection
 ```
 
-```rb
+### Lists
-module MyModule # :nodoc: all
+
+```text
+* First item
+* Second item
+
+1. First step
+2. Second step
 ```
 
 ### Definition lists
 
-```rb
+```text
-# == Definition lists
+name:: description
-#
++option+:: option description
-# list::  hi.
-# +foo+:: parameterized
 ```
 
-```rb
+```text
-# == Definition lists
+[name] description
-# [foo]   also
+[other] another description
-# [bar]   like this
 ```
 
-### Return types
+## Directives
 
-```rb
+### Hide documentation
-# @return [String]
+
-# @return [String, nil] the name
+```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
+#   readlines(sep = $/)        -> array
-#   ARGF.readlines(limit)      -> array
+#   readlines(limit)           -> array
-#   ARGF.readlines(sep, limit) -> array
+#   readlines(sep, limit)      -> array
-#
-#   ARGF.to_a(sep=$/)     -> array
-#   ARGF.to_a(limit)      -> array
-#   ARGF.to_a(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}
 
-* <https://docs.ruby-lang.org/en/2.1.0/RDoc/Markup.html>
+- <https://ruby-doc.org/3.4/RDoc/MarkupReference.html>
-* <https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md>
+- <https://ruby-doc.org/3.4/contributing/documentation_guide_md.html>
-* <https://rubydoc.info/gems/yard/file/docs/Tags.md>
 {: .-also-see}

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<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}