### Define Template Sections in setup.rb

Source: https://github.com/lsegal/yard/wiki/Templates

Use the `init` method in `setup.rb` to define the sections that make up a template. This example shows a basic setup with three sections.

```ruby
def init
  sections :section1, :section2, :section3
end
```

--------------------------------

### Example Tag with Title

Source: https://github.com/lsegal/yard/wiki/Tags

Demonstrates the `@example` tag syntax where the first line of metadata is extracted as the title. This is useful for providing code examples within documentation.

```ruby
# @example Inspect an element
#   myobj.inspect #=> #<Object:0x123525>
```

--------------------------------

### Install and Load a YARD Plugin

Source: https://github.com/lsegal/yard/blob/main/docs/GettingStarted.md

Install a YARD plugin using gem install and then load it using the --plugin switch with either the short or full plugin name.

```bash
$ gem install yard-custom-plugin
...
$ yard doc --plugin custom-plugin
or
$ yard doc --plugin yard-custom-plugin
```

```bash
$ gem install yard-rspec

You can then load the plugin with:

    $ yard doc --plugin rspec
```

--------------------------------

### Serve Documentation for All Installed Gems

Source: https://github.com/lsegal/yard/blob/main/README.md

Serve documentation for all installed RubyGems. This command will also build documentation for any gems that have not been previously scanned.

```sh
$ yard server --gems
```

--------------------------------

### Generate Guide-Based Documentation

Source: https://github.com/lsegal/yard/blob/main/docs/WhatsNew.md

Use the `-t guide` template with `yardoc` to generate documentation solely for extra files like READMEs or guides. API documentation can be embedded using `{render:Object}`.

```bash
yardoc -t guide - README GettingStarted FAQ TroubleShooting LICENSE
```

--------------------------------

### Example Usage of #m

Source: https://github.com/lsegal/yard/blob/main/spec/templates/examples/tag001.txt

Demonstrates basic usage of the #m method. This is a simple example for illustration.

```ruby
car.wash
```

```ruby
a = String.new
flip(a.reverse)
```

--------------------------------

### Example Tag with Title

Source: https://github.com/lsegal/yard/wiki/Tags

Shows an example snippet of code for an object. The first line is an optional title.

```ruby
@example Reverse a string
  "mystring".reverse #=> "gnirtsym"
```

--------------------------------

### Override Default Class Template Setup

Source: https://github.com/lsegal/yard/wiki/Templates

Example of a `setup.rb` file within a custom template path that overrides the default 'class' template by adding a new section.

```ruby
def init
  super
  sections.push :customsection
end
```

--------------------------------

### Install yard-rspec Plugin

Source: https://github.com/lsegal/yard/wiki/GettingStarted

Install the yard-rspec plugin using gem install or clone the project to try out the example.

```bash
$ gem install yard-rspec -s http://gemcutter.org
```

```bash
$ git clone git://github.com/lsegal/yard-spec-plugin
```

--------------------------------

### Serve Local Project Documentation (`yard server`)

Source: https://github.com/lsegal/yard/blob/main/docs/WhatsNew.md

Starts a local documentation server for the active project. Use `--reload` for incremental updates.

```bash
$ yard server
```

```bash
$ yard server --reload
```

--------------------------------

### Install YARD

Source: https://github.com/lsegal/yard/blob/main/README.md

Install YARD using the RubyGems package manager. Use `sudo` if installing on a POSIX system as root.

```sh
$ gem install yard
```

--------------------------------

### Serve Local Project Documentation

Source: https://github.com/lsegal/yard/blob/main/README.md

Start a local web server to view your project's documentation. The server will automatically parse the source if it hasn't been scanned yet.

```sh
$ yard server
```

--------------------------------

### Install yard-doc-core gem

Source: https://github.com/lsegal/yard/blob/main/docs/WhatsNew.md

Install the yard-doc-core gem to enable yri lookups for Ruby core classes. Use the --version switch to specify a Ruby version.

```bash
$ sudo gem install yard-doc-core
# now you can use:
$ yri String
```

```bash
$ sudo gem install --version '= 1.8.6' yard-doc-core
```

--------------------------------

### Configure YARD Options with .yardopts

Source: https://github.com/lsegal/yard/blob/main/docs/GettingStarted.md

Example of how to use a `.yardopts` file to store common command-line arguments for `yardoc`. Any extra switches passed to the command-line will be appended to these options.

```bash
yardoc --no-private --protected app/**/*.rb - README LEGAL COPYING
```

```bash
--no-private --protected app/**/*.rb - README LEGAL COPYING
```

```bash
yardoc
```

--------------------------------

### Option Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Describes an options hash in a method. Takes parameter name, types, key, default value, and description.

```ruby
# @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 
def send_email(opts = {})
end
```

--------------------------------

### Note Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Creates an emphasized note for users to read about the object.

```ruby
@note This method should only be used in outer space.
```

--------------------------------

### Parameter Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Defines method parameters with optional types and a description.

```ruby
@param [optional, types, ...] argname description
```

--------------------------------

### Install specific yard-doc-core version

Source: https://github.com/lsegal/yard/wiki/WhatsNew

Install a specific version of the yard-doc-core gem using the --version switch. This is useful for compatibility with older Ruby versions.

```bash
$ sudo gem install --version '= 1.8.6' yard-doc-core
```

--------------------------------

### See Also Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

"See Also" references for an object. Accepts URLs or other references.

```ruby
@see
```

--------------------------------

### Identity Map Example

Source: https://github.com/lsegal/yard/blob/main/docs/CodeObjects.md

Demonstrates the identity map implementation where creating a new object with an existing path returns the same Ruby object.

```ruby
id = ClassObject.new(:root, "MyClass").object_id
ClassObject.new(:root, "MyClass").object_id
```

--------------------------------

### Return Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Describes the return value of a method, including optional types.

```ruby
@return [optional, types, ...] description
```

--------------------------------

### Raise Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Describes an Exception that a method may throw.

```ruby
@raise [ExceptionClass] description
```

--------------------------------

### YARD Tag Syntax Example

Source: https://github.com/lsegal/yard/blob/main/docs/Tags.md

Illustrates the basic syntax for meta-data tags and directives in YARD comments.

```ruby
# @meta_data_tag some data
# @!directive_tag some data
class Foo; end
```

--------------------------------

### Include Module Template in Class Setup

Source: https://github.com/lsegal/yard/wiki/Templates

This line in `default/class/html/setup.rb` includes the 'default/module/html' template, allowing class templates to utilize module's erb files.

```ruby
include T('default/module/html')
```

--------------------------------

### Method DSL Method Example

Source: https://github.com/lsegal/yard/wiki/Tags

Recognizes a DSL class method with the given name and optional signature. Only used with DSL methods.

```ruby
@method method_signature(opts = {}, &block)
```

--------------------------------

### Build YARD Databases for Gems

Source: https://github.com/lsegal/yard/blob/main/README.md

Generate YARD documentation databases for installed gems to enable `yri` lookups. These databases are stored in `~/.yard` if sudo access is unavailable.

```sh
$ yard gems
```

--------------------------------

### Overload Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Shows the @overload tag syntax, where the first line is the method signature and subsequent lines describe it.

```plaintext
@overload request(method = :get, url = 'http://example.com')
  Performs a request on +url+
  @param [Symbol] method the request method
  @param [String] url the URL to perform the request on
  @return [String] the result body (no headers)
```

--------------------------------

### Overload Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Describes method overloads with different parameters or return types. The first line declares the signature.

```ruby
# @overload set(key, value)
#   Sets a value on key
#   @param [Symbol] key describe key param
#   @param [Object] value describe value param
# @overload set(value)
#   Sets a value on the default key :foo
#   @param [Object] value describe value param
def set(*args)
end
```

--------------------------------

### Get Subarray by Start and Length (C)

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/array.c.txt

Extracts a subarray starting at a given index and continuing for a specified length. Handles boundary conditions and returns nil for invalid inputs.

```c
VALUE
ruby_ary_subseq(VALUE ary, long beg, long len)
{
    VALUE klass;
    long alen = RARRAY_LEN(ary);

    if (beg > alen) return Qnil;
    if (beg < 0 || len < 0) return Qnil;

    if (alen < len || alen < beg + len) {
	len = alen - beg;
    }
    klass = rb_obj_class(ary);
    if (len == 0) return ary_new(klass, 0);

    return ary_make_partial(ary, klass, beg, len);
}
```

--------------------------------

### Get Line Information from AstNode

Source: https://github.com/lsegal/yard/blob/main/docs/Parser.md

Nodes provide `#line` for the starting line number and `#line_range` for the range of lines (including newlines) the node spans in the source.

```ruby
ast[0].type       #=> :if
ast[0].line       #=> 1
ast[0].line_range #=> 1..3 (note the newlines in the source)
```

--------------------------------

### Macro Variable Interpolation Range Example

Source: https://github.com/lsegal/yard/wiki/Tags

Shows how to interpolate a range of arguments, including the method name and its arguments, separated by commas.

```ruby
$0-1 # => Interpolates to "create_method_with_args, foo"
```

--------------------------------

### Query Documentation by Tag Text

Source: https://github.com/lsegal/yard/blob/main/README.md

Generate documentation for objects matching a specific tag's text value. This example filters for objects with an '@api' tag set to 'public'.

```sh
--query '@api.text == "public"'
```

```sh
--query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
```

```sh
--query 'has_tag?(:api) && tag(:api).text == "public"'
```

--------------------------------

### Struct Definition Examples

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/class_handler_001.rb.txt

Demonstrates defining classes that inherit from 'Struct', including a basic 'RegularStruct', one inheriting from '::Struct', and 'Point' and 'AnotherPoint' with defined members.

```ruby
class RegularStruct < Struct; end
class RegularStruct2 < ::Struct; end

class Point < Struct.new(:x, :y, :z)
end

class AnotherPoint < Struct.new('XPoint', :a, :b, :c, :description)
end
```

--------------------------------

### Install yard-doc-core gem

Source: https://github.com/lsegal/yard/wiki/WhatsNew

Install the yard-doc-core gem to enable yri lookups for Ruby core classes. This command installs the gem for the latest supported Ruby version.

```bash
$ sudo gem install yard-doc-core
```

--------------------------------

### Generate custom menu list in fulldoc/setup.rb

Source: https://github.com/lsegal/yard/blob/main/docs/Templates.md

Define a method in the `fulldoc` template's `setup.rb` to generate HTML for a custom menu type. This method should load items from the Registry and use `asset` to create the HTML file.

```ruby
def generate_feature_list

  # load all the features from the Registry
  @items = Registry.all(:feature)
  @list_title = "Feature List"
  @list_type = "feature"

  # optional: the specified stylesheet class
  # when not specified it will default to the value of @list_type
  @list_class = "class"

  # Generate the full list html file with named feature_list.html
  # @note this file must be match the name of the type
  asset('feature_list.html', erb(:full_list))
end
```

--------------------------------

### Method with Multiple Overloads and Parameters

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/method_handler_001.rb.txt

Demonstrates a method `foo` accepting variable arguments (`*args`) and includes documentation for multiple overloads with different parameter types and return values.

```Ruby
# @param a [Fixnum]
  # @overload def bar(a, b = 1)
  #   @param a [String]
  #   @return [String]
  # @overload def baz(b, c)
  #   @return [Fixnum]
  # @overload bang(d, e)
  def foo(*args); end
```

--------------------------------

### Yield with Parameters and Documentation

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/yield_handler_001.rb.txt

Demonstrates yielding multiple parameters with associated documentation for yield and yield parameters.

```ruby
class Testing
  # Has yield and yieldparam documentation
  # @yield [a, b] Blah
  # @yieldparam a Blah
  # @yieldparam b Blah
  def mymethod2
    yield(b, a) # Yield something else
  end
end
```

--------------------------------

### Install ripper gem

Source: https://github.com/lsegal/yard/wiki/WhatsNew

Install the ripper gem to enable YARD's improved parsing capabilities for Ruby 1.8.7.

```bash
gem install ripper
```

--------------------------------

### Serve Documentation with Live Reloading

Source: https://github.com/lsegal/yard/blob/main/README.md

Enable live reloading when serving documentation to preview changes instantly. YARD will reload modified files on each request, allowing for real-time feedback.

```sh
$ yard server --reload
```

--------------------------------

### Instance Method with Docstring

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/method_handler_001.rb.txt

An instance method `initialize` with a docstring but no explicit return type specified.

```Ruby
# A docstring but no return type
def initialize; end
```

--------------------------------

### Query Documentation with `yri`

Source: https://github.com/lsegal/yard/blob/main/README.md

Use the `yri` command-line tool for fast, ri-style access to your project's cached YARD database. Note that class methods should not use the '::' separator.

```sh
$ yri YARD::Handlers::Base#register
$ yri File.relative_path
```

--------------------------------

### Example of Duck-Type Usage in @param Tag

Source: https://github.com/lsegal/yard/blob/main/docs/Tags.md

Use duck-types for @param tags to specify that a parameter should respond to certain methods. This example shows a parameter 'io' that must respond to '#read'.

```ruby
# Reads from any I/O object.
# @param io [#read] the input object to read from
def read(io) io.read end
```

--------------------------------

### Documenting a method with RDoc syntax

Source: https://github.com/lsegal/yard/wiki/GettingStarted

This example shows the traditional RDoc syntax for documenting a method, including parameters and return values. It highlights the free-form nature which can be difficult for machines to parse.

```ruby
# Converts the object into textual markup given a specific `format` 
# (defaults to `:html`)
#
# == Parameters:
# format::
#   A Symbol declaring the format to convert the object to. This 
#   can be `:text` or `:html`.
#
# == Returns:
# A string representing the object in a specified
# format.
#
def to_format(format = :html)
  # format the object
end
```

--------------------------------

### Author Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Lists the author(s) of a class/method.

```ruby
@author Full Name
```

--------------------------------

### Yielding Super

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/yield_handler_001.rb.txt

Example of yielding the result of a `super` call.

```ruby
class Testing
  def mymethod9
    yield super
  end
end
```

--------------------------------

### Documenting a method with YARD tags

Source: https://github.com/lsegal/yard/wiki/GettingStarted

This example demonstrates how to document a Ruby method using YARD's structured tag syntax. Tags like `@param` and `@return` provide semantic metadata that YARD can easily parse for documentation generation.

```ruby
# Converts the object into textual markup given a specific format.
#
# @param [Symbol] format the format type, `:text` or `:html`
# @return [String] the object converted into the expected format.
def to_format(format = :html)
  # format the object
end
```

--------------------------------

### Foo Class Instance Methods

Source: https://github.com/lsegal/yard/blob/main/spec/templates/examples/module002.html

Details on instance methods available for the Foo class.

```APIDOC
## #foo

### Description
Instance method 'foo' for the Foo class.

### Method
Instance Method

### Endpoint
N/A

### Parameters
None

### Request Example
None

### Response
None
```

--------------------------------

### Module A Instance Methods

Source: https://github.com/lsegal/yard/blob/main/spec/templates/examples/module001.html

Details on instance methods available in Module A.

```APIDOC
## #a

### Description
This instance method is also known as #b.

### Method
Instance Method

### Endpoint
N/A

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
None specified
```

```APIDOC
## #test_multi_overload(*args)

### Description
Handles multiple overloads for the test_multi_overload method.

### Method
Instance Method

### Endpoint
N/A

### Parameters
*   args (*args) - Variable length argument list.

### Request Example
None

### Response
#### Success Response (200)
None specified
```

```APIDOC
## #test_overload(a)

### Description
Overloaded method with a single parameter.

### Method
Instance Method

### Endpoint
N/A

### Parameters
*   a (String) - hi

### Request Example
None

### Response
#### Success Response (200)
None specified
```

```APIDOC
## #void_meth

### Description
This method returns an undefined value.

### Method
Instance Method

### Endpoint
N/A

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
None specified
```

--------------------------------

### Build gem documentation index

Source: https://github.com/lsegal/yard/wiki/WhatsNew

Use this command to build a .yardoc file for all installed gems, enabling yri to perform lookups on them. YARD will attempt to write to the gem path, or to `~/.yard/gem_index/` if write access is denied.

```bash
$ sudo yardoc --build-gems
```

--------------------------------

### Abstract Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Marks a class/module/method as abstract with optional implementor information.

```ruby
@abstract Subclass and override {#run} to implement a custom Threadable class.
```

--------------------------------

### Generate Documentation with Default Glob and Extra Files

Source: https://github.com/lsegal/yard/blob/main/README.md

Generate YARD documentation using the default glob (`lib/**/*.rb`) and including extra files like README and LICENSE.

```sh
$ yardoc - README LICENSE FAQ
```

--------------------------------

### Basic Yield Example

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/yield_handler_001.rb.txt

A simple method that yields control without passing any arguments.

```ruby
class Testing
  # Should document this
  def mymethod
    yield
  end
end
```

--------------------------------

### Initialize Multifile Class in C

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/multifile.c.txt

Initializes the C class 'Multifile' and defines its methods 'extra' and 'hello_mars'.

```c
void
Init_Multifile(void)
{
    rb_cMultifile  = rb_define_class("Multifile", rb_cObject);
    rb_define_method(rb_cMultifile, "extra", rb_extra, 1); /* in extra.c */
    rb_define_method(rb_cMultifile, "hello_mars", rb_hello_mars, 1);
}
```

--------------------------------

### Generate documentation with query argument

Source: https://github.com/lsegal/yard/wiki/WhatsNew

Use the --query argument with yardoc to select which classes, modules, or methods to include in documentation based on their data or meta-data. This example generates documentation for public API methods.

```bash
--query '@api.text == "public"'
```

--------------------------------

### Deprecated Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Marks a method/class as deprecated with an optional reason or alternative references.

```ruby
@deprecated Describe the reason or provide alt. references here
```

--------------------------------

### Constructor: initialize

Source: https://github.com/lsegal/yard/blob/main/spec/templates/examples/class001.html

Initializes a new instance of class A. This is the constructor method.

```APIDOC
## initialize(test)

### Description
constructor method!.

### Method
initialize

### Parameters
#### Path Parameters
- **test** (any) - Required - Description of the test parameter

### Response
#### Success Response (200)
- **A** (object) - An instance of class A
```

--------------------------------

### API Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Declares the API that the object belongs to. Useful for performing queries.

```ruby
@api freeform text
```

--------------------------------

### Hello World Function for wxRect

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/namespace.cpp.txt

A placeholder function named 'hello_world' that formats a string similar to the inspect method. Its exact purpose within the namespace is not detailed.

```cpp
VALUE _hello_world(VALUE self)
{
    return rb_sprintf( "%s(%d, %d, %d, %d)",
        rb_obj_classname( self ),
        FIX2INT(_getX(self)),
        FIX2INT(_getY(self)),
        FIX2INT(_getWidth(self)),
        FIX2INT(_getHeight(self)));
}
```

--------------------------------

### Example Usage of @version Tag

Source: https://github.com/lsegal/yard/wiki/Tags

The @version tag specifies the version of a class, module, or method.

```ruby
@version 1.0
```

--------------------------------

### Private Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Defines an object as private, hiding it from documentation with the `--no-private` switch.

```ruby
@private
```

--------------------------------

### Class Method Definition Example

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/method_handler_001.rb.txt

A simple class method `method2` defined using `self.method2`.

```Ruby
def self.method2; end
```

--------------------------------

### Macro Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Registers or expands a new macro. The name parameter is never optional.

```ruby
@macro [new|attached] macro_name
  The macro contents to expand
```

--------------------------------

### Query Documentation for Multiple Tags

Source: https://github.com/lsegal/yard/blob/main/README.md

Generate documentation for objects that possess both a return tag and a param tag. Multiple `--query` arguments can be used.

```sh
--query '@return' --query '@param'
```

```sh
--query '@return && @param'
```

--------------------------------

### Attribute Tag Example for Structs

Source: https://github.com/lsegal/yard/wiki/Tags

Declares an attribute from the docstring of a class. Meant for Struct classes only.

```ruby
@attr [Types] attribute_name a full description of the attribute
```

--------------------------------

### Manually Declare Plugins with --plugin

Source: https://github.com/lsegal/yard/blob/main/docs/WhatsNew.md

Plugins are no longer auto-loaded. Declare plugins in `.yardopts` or use the `--plugin` switch.

```bash
yard --plugin PLUGINNAME
```

--------------------------------

### Example Usage of @since Tag

Source: https://github.com/lsegal/yard/wiki/Tags

The @since tag indicates the version in which a feature or object was first introduced.

```ruby
@since 1.2.4
```

--------------------------------

### Include Module from a Constant

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/mixin_handler_001.rb.txt

Shows how to include a module by referencing it through a constant.

```ruby
module FromConstant; end
FromConstant.include A
```

--------------------------------

### Freeform Tag Data Example

Source: https://github.com/lsegal/yard/wiki/Tags

Illustrates a simple tag with freeform data following the tag name.

```plaintext
@tagname data here
```

--------------------------------

### Rect#hello_world

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/namespace.cpp.txt

A method that returns a formatted string, likely for demonstration or testing purposes.

```APIDOC
## Rect#hello_world

### Description
Returns a formatted string. This method appears to be for demonstration or testing.

### Method
hello_world

### Return Value
String - A formatted string.

### Example
```ruby
rect = RubyWX::Rect.new(10, 20, 30, 40)
puts rect.hello_world
# Output: Rect(10, 20, 30, 40) (example output based on implementation)
```
```

--------------------------------

### Instance Method: #baz_xyz

Source: https://github.com/lsegal/yard/blob/main/spec/templates/examples/module004.html

Instance method 'baz_xyz' is included from the Baz::XYZ module.

```APIDOC
## #baz_xyz

### Description
Instance method included from Baz::XYZ.

### Source
Included from module Baz::XYZ.
```

--------------------------------

### Get array length

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/array.c.txt

The `length` method returns the number of elements in an array. It can be zero for an empty array.

```ruby
[ 1, 2, 3, 4, 5 ].length   #=> 5
[].length                  #=> 0
```

--------------------------------

### Force re-parsing of all gems

Source: https://github.com/lsegal/yard/wiki/WhatsNew

Use this command to force YARD to re-parse all installed gems, updating their .yardoc files.

```bash
yardoc --re-build-gems
```

--------------------------------

### Instance Method: #xyz

Source: https://github.com/lsegal/yard/blob/main/spec/templates/examples/module004.html

Instance method 'xyz' is included from the Foo module.

```APIDOC
## #xyz

### Description
Docs for xyz.

### Source
Included from module Foo.
```

--------------------------------

### List Available Markup Types

Source: https://github.com/lsegal/yard/blob/main/docs/WhatsNew.md

Run `yard markups` to list all available markup types, their providers, and associated file extensions.

```bash
$ yard markups
```

--------------------------------

### Scope Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

Sets the scope of a DSL method to 'class' or 'instance'. Only applicable to DSL method calls.

```ruby
@scope class|instance
```

--------------------------------

### Documenting Method Parameters and Return Types with YARD Tags

Source: https://github.com/lsegal/yard/blob/main/README.md

Demonstrates how to use YARD's @param and @return tags to specify types for method parameters and return values. This provides a consistent way to document method signatures.

```ruby
# Reverses the contents of a String or IO object.
#
# @param contents [String, #read] the contents to reverse
# @return [String] the contents reversed lexically
def reverse(contents)
  contents = contents.read if contents.respond_to? :read
  contents.reverse
end
```

--------------------------------

### Create a New Macro with a Simple Description

Source: https://github.com/lsegal/yard/wiki/Tags

A new macro can be created with the '[new]' flag, followed by the macro name and its documentation content.

```ruby
# @macro [new] the_macro_name
# Returns a string!
def foo; end
```

--------------------------------

### Basic Class Definition

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/class_handler_001.rb.txt

A simple class definition for 'Zebra'. The surrounding comments indicate it's a basic example.

```ruby
class Zebra
end
```

--------------------------------

### Writeonly Attribute Tag Example for Structs

Source: https://github.com/lsegal/yard/wiki/Tags

Declares a writeonly attribute from the docstring of class. Meant for Struct classes only.

```ruby
@attr_writer [Types] name description of writeonly attribute
```

--------------------------------

### Readonly Attribute Tag Example for Structs

Source: https://github.com/lsegal/yard/wiki/Tags

Declares a readonly attribute from the docstring of a class. Meant for Struct classes only.

```ruby
@attr_reader [Types] name description of a readonly attribute
```

--------------------------------

### Using the XYZ Macro

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/method_handler_001.rb.txt

Demonstrates the usage of the `xyz` macro to define a method named `:a`.

```Ruby
xyz :a
```

--------------------------------

### Array#drop Example

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/array.c.txt

Drops the first n elements from an array and returns the rest. Raises an ArgumentError if n is negative.

```ruby
a = [1, 2, 3, 4, 5, 0]
a.drop(3)             #=> [4, 5, 0]
```

--------------------------------

### Instance Method: #foo

Source: https://github.com/lsegal/yard/blob/main/spec/templates/examples/module004.html

This is an instance method defined directly within Class A.

```APIDOC
## #foo

### Description
This method is defined in Class A.

### Method
#foo

### Source
```ruby
def foo; end
```
```

--------------------------------

### Alias Methods

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/dsl_handler_001.rb.txt

Demonstrates aliased methods and their documentation.

```APIDOC
## main_foo1

### Description
Success main_foo1

### Method
Alias Method

### Endpoint
N/A

### Response
#### Success Response (200)
- **return** (N/A) - No specific return type documented.
```

```APIDOC
## alias_foo1

### Description
Success alias_foo1

### Method
Alias Method

### Endpoint
N/A

### Response
#### Success Response (200)
- **return** (N/A) - No specific return type documented.
```

```APIDOC
## main_foo2

### Description
Success main_foo2

### Method
Alias Method

### Endpoint
N/A

### Response
#### Success Response (200)
- **return** (N/A) - No specific return type documented.
```

```APIDOC
## alias_foo2

### Description
Success alias_foo2

### Method
Alias Method

### Endpoint
N/A

### Response
#### Success Response (200)
- **return** (N/A) - No specific return type documented.
```

--------------------------------

### Getting First and Last Array Elements

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/array.c.txt

Retrieve the first and last elements of an array using the #first and #last methods.

```ruby
arr.first #=> 1
arr.last  #=> 6
```

--------------------------------

### Configure Yard Options with .yardopts

Source: https://github.com/lsegal/yard/wiki/GettingStarted

Use a .yardopts file to store common yardoc command-line arguments. Any arguments passed on the command line will be appended to the options in this file.

```bash
--no-private --protected app/**/*.rb - README LEGAL COPYING
```

--------------------------------

### Get Shared Array Number

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/array.c.txt

Retrieves the number associated with a shared root array. Asserts that the array is a shared root.

```c
#define ARY_SHARED_NUM(ary) \
    (assert(ARY_SHARED_ROOT_P(ary)), RARRAY(ary)->as.heap.aux.capa)
```

--------------------------------

### Display Objects with Layout and README

Source: https://github.com/lsegal/yard/blob/main/docs/WhatsNew.md

Include the README file at the top of a onefile layout generated by `yard display` using the `--readme` switch.

```bash
$ yard display --layout onefile -f html --readme README.md OBJECT > out.html
```

--------------------------------

### Yield with Multiple Arguments (Variant)

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/yield_handler_001.rb.txt

A method yielding multiple arguments, similar to `mymethod2` but potentially with different context or setup.

```ruby
class Testing
  def mymethod6
    yield(b, a)
  end
end
```

--------------------------------

### Foo Bar Method

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/dsl_handler_001.rb.txt

Documentation for the foo_bar method.

```APIDOC
## foo_bar

### Description
The foo method.

### Method
Class Method

### Endpoint
N/A

### Parameters
#### Path Parameters
- **a** (String) - Required - 
- **b** (N/A) - Required - 
- **c** (N/A) - Required - 

### Response
#### Success Response (200)
- **return** (N/A) - No specific return type documented.
```

--------------------------------

### Array#drop_while Example

Source: https://github.com/lsegal/yard/blob/main/spec/parser/examples/array.c.txt

Drops elements from the beginning of an array until the block returns nil or false. Returns an array with the remaining elements.

```ruby
a = [1, 2, 3, 4, 5, 0]
a.drop_while {|i| i < 3 }   #=> [3, 4, 5, 0]
```

--------------------------------

### Directive Method

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/dsl_handler_001.rb.txt

Demonstrates a method with a directive.

```APIDOC
## attach

### Description
Include Bar

### Method
Directive Method

### Endpoint
N/A

### Parameters
#### Path Parameters
- **x** (N/A) - Required - 

### Response
#### Success Response (200)
- **return** (N/A) - No specific return type documented.
```

--------------------------------

### Private API Tag Example

Source: https://github.com/lsegal/yard/wiki/Tags

The special name `@api private` displays a notice in documentation if listed, indicating the method is not to be used.

```ruby
@api private
```

--------------------------------

### DSL Methods

Source: https://github.com/lsegal/yard/blob/main/spec/handlers/examples/dsl_handler_001.rb.txt

Demonstrates DSL methods defined in a module.

```APIDOC
## foo

### Description
Returns String for foo

### Method
DSL Method

### Endpoint
N/A

### Response
#### Success Response (200)
- **return** (String) - No specific return type documented.
```

```APIDOC
## bar

### Description
Returns Integer for bar

### Method
DSL Method

### Endpoint
N/A

### Response
#### Success Response (200)
- **return** (Integer) - No specific return type documented.
```

--------------------------------

### Freeform Tag Data With Title Example

Source: https://github.com/lsegal/yard/wiki/Tags

Demonstrates a tag where the first line serves as a title and subsequent indented lines are the data.

```plaintext
@example Reverse a string
  "hello world".reverse
```