yard

Create the documentation

$ yard

$ yard --one-file

$ yard stats --list-undoc

Since YARD is a Ruby gem, its invocation typically follows a subcommand pattern:

yard [global options] <command> [command options]

Common usage examples include:
yard doc [files...] [options] (Generates documentation)
yard server [options] (Starts a live documentation server)
yard stats [options] (Shows documentation statistics)
yard config [options] (Manages YARD configuration)

Global Options (applicable to any yard command):
    

--help, -h
    Displays the help message for YARD or a specific command.

--version, -v
    Displays the YARD version number.

--debug
    Enables verbose debug output.

--profile
    Enables profiling mode to show performance statistics.

--gem-home PATH
    Specifies the path to the RubyGems installation directory.

Common "doc" Command Options:
    

--output FILE, -o FILE
    Specifies the output directory for generated documentation. Default is doc/.

--template TEMPLATE_NAME
    Specifies the template to use for rendering documentation (e.g., default, fulldoc).

--ext FILE_LIST
    Specifies a comma-separated list of file extensions to parse as Ruby source.

--no-public
    Excludes public methods from documentation.

--no-private
    Excludes private methods from documentation.

--no-undoc
    Excludes undocumented objects from the generated output.

--markup MARKUP_LANG
    Forces the markup language for all files (e.g., markdown, rdoc).

YARD (Yet Another Ruby Documentation) is an advanced tool used primarily by Ruby developers to generate comprehensive API documentation from source code comments and structure. Unlike typical Linux commands, YARD is not a built-in utility; it is a Ruby gem that must be installed via the RubyGems package manager (e.g., gem install yard).

It parses Ruby code, including classes, modules, methods, and constants, along with specially formatted comments, to produce highly navigable documentation, most commonly in HTML format. YARD supports a rich markup language (including Markdown), custom tags, and a powerful plugin architecture, allowing users to extend its functionality and customize output extensively. It's widely adopted in the Ruby ecosystem for documenting libraries, frameworks, and applications.

YARD is not a standard Linux command or a pre-installed system utility. It is a Ruby-specific tool that requires a Ruby environment and must be installed separately as a gem (gem install yard). Its functionality is primarily relevant to Ruby development projects. Due to its extensive features and subcommand structure, it can have a steep learning curve for advanced customization.

One of YARD's most powerful features is its support for custom documentation tags (e.g., @note, @example, @todo) beyond the standard RDoc/JSDoc set. This allows developers to enrich their documentation with project-specific information. Furthermore, its plugin architecture enables extensive customization and extension of its parsing, processing, and output generation capabilities.

The yard server command provides a local web server to view documentation live as you develop, automatically refreshing when changes are detected in your source files. This greatly streamlines the documentation writing and review process.

YARD allows developers to choose their preferred markup language for docstrings, supporting Markdown, RDoc, and other custom formats. This flexibility caters to different team preferences and existing documentation styles.

YARD was created by Loren Segal and first released in the late 2000s, gaining popularity as a powerful and flexible alternative to Ruby's then-standard documentation tool, RDoc. It was designed to address limitations in RDoc, particularly around custom tags, extensibility, and better support for complex project structures. Over the years, YARD has evolved into the de-facto standard for documenting Ruby libraries and applications, known for its robust parsing capabilities and highly customizable output.

Ruby, gem(1) (RubyGems package manager), Bundler (Ruby dependency manager), RDoc (Another Ruby documentation tool)