### Home Classes Methods

### In Files

- lib/yard/cli/yardoc.rb

### Parent

Command

### Methods

- ::new
- #all_objects
- #description
- #parse_arguments
- #run
- #yardopts

### Files

- LICENSE.txt
- MIT.txt

### Class/Module Index

Quicksearch

- YARD
- YARD::CLI
- YARD::CLI::Command
- YARD::CLI::CommandParser
- YARD::CLI::Config
- YARD::CLI::Diff
- YARD::CLI::Gems
- YARD::CLI::Graph
- YARD::CLI::GraphOptions
- YARD::CLI::Help
- YARD::CLI::I18n
- YARD::CLI::List
- YARD::CLI::Server
- YARD::CLI::Stats
- YARD::CLI::YRI
- YARD::CLI::Yardoc
- YARD::CLI::YardocOptions
- YARD::CodeObjects
- YARD::CodeObjects::Base
- YARD::CodeObjects::ClassObject
- YARD::CodeObjects::ClassVariableObject
- YARD::CodeObjects::CodeObjectList
- YARD::CodeObjects::ConstantObject
- YARD::CodeObjects::ExtendedMethodObject
- YARD::CodeObjects::ExtraFileObject
- YARD::CodeObjects::MacroObject
- YARD::CodeObjects::MethodObject
- YARD::CodeObjects::ModuleObject
- YARD::CodeObjects::NamespaceObject
- YARD::CodeObjects::Proxy
- YARD::CodeObjects::ProxyMethodError
- YARD::CodeObjects::RootObject
- YARD::Config
- YARD::Docstring
- YARD::DocstringParser
- YARD::Handlers
- YARD::Handlers::Base
- YARD::Handlers::C
- YARD::Handlers::C::AliasHandler
- YARD::Handlers::C::AttributeHandler
- YARD::Handlers::C::Base
- YARD::Handlers::C::ClassHandler
- YARD::Handlers::C::ConstantHandler
- YARD::Handlers::C::HandlerMethods
- YARD::Handlers::C::InitHandler
- YARD::Handlers::C::MethodHandler
- YARD::Handlers::C::MixinHandler
- YARD::Handlers::C::ModuleHandler
- YARD::Handlers::C::OverrideCommentHandler
- YARD::Handlers::C::PathHandler
- YARD::Handlers::C::StructHandler
- YARD::Handlers::C::SymbolHandler
- YARD::Handlers::NamespaceMissingError
- YARD::Handlers::Processor
- YARD::Handlers::Ruby
- YARD::Handlers::Ruby::AliasHandler
- YARD::Handlers::Ruby::AttributeHandler
- YARD::Handlers::Ruby::Base
- YARD::Handlers::Ruby::ClassConditionHandler
- YARD::Handlers::Ruby::ClassHandler
- YARD::Handlers::Ruby::ClassVariableHandler
- YARD::Handlers::Ruby::CommentHandler
- YARD::Handlers::Ruby::ConstantHandler
- YARD::Handlers::Ruby::DSLHandler
- YARD::Handlers::Ruby::DSLHandlerMethods
- YARD::Handlers::Ruby::ExceptionHandler
- YARD::Handlers::Ruby::ExtendHandler
- YARD::Handlers::Ruby::HandlesExtension
- YARD::Handlers::Ruby::Legacy
- YARD::Handlers::Ruby::Legacy::AliasHandler
- YARD::Handlers::Ruby::Legacy::AttributeHandler
- YARD::Handlers::Ruby::Legacy::Base
- YARD::Handlers::Ruby::Legacy::ClassConditionHandler
- YARD::Handlers::Ruby::Legacy::ClassHandler
- YARD::Handlers::Ruby::Legacy::ClassVariableHandler
- YARD::Handlers::Ruby::Legacy::CommentHandler
- YARD::Handlers::Ruby::Legacy::ConstantHandler
- YARD::Handlers::Ruby::Legacy::DSLHandler
- YARD::Handlers::Ruby::Legacy::ExceptionHandler
- YARD::Handlers::Ruby::Legacy::ExtendHandler
- YARD::Handlers::Ruby::Legacy::MethodHandler
- YARD::Handlers::Ruby::Legacy::MixinHandler
- YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler
- YARD::Handlers::Ruby::Legacy::ModuleHandler
- YARD::Handlers::Ruby::Legacy::PrivateConstantHandler
- YARD::Handlers::Ruby::Legacy::VisibilityHandler
- YARD::Handlers::Ruby::Legacy::YieldHandler
- YARD::Handlers::Ruby::MethodCallWrapper
- YARD::Handlers::Ruby::MethodConditionHandler
- YARD::Handlers::Ruby::MethodHandler
- YARD::Handlers::Ruby::MixinHandler
- YARD::Handlers::Ruby::ModuleFunctionHandler
- YARD::Handlers::Ruby::ModuleHandler
- YARD::Handlers::Ruby::PrivateConstantHandler
- YARD::Handlers::Ruby::StructHandlerMethods
- YARD::Handlers::Ruby::TestNodeWrapper
- YARD::Handlers::Ruby::VisibilityHandler
- YARD::Handlers::Ruby::YieldHandler
- YARD::I18n
- YARD::I18n::Locale
- YARD::I18n::Message
- YARD::I18n::Messages
- YARD::I18n::PotGenerator
- YARD::I18n::Text
- YARD::Logger
- YARD::Options
- YARD::Parser
- YARD::Parser::Base
- YARD::Parser::C
- YARD::Parser::C::BodyStatement
- YARD::Parser::C::CParser
- YARD::Parser::C::Comment
- YARD::Parser::C::CommentParser
- YARD::Parser::C::Statement
- YARD::Parser::C::ToplevelStatement
- YARD::Parser::OrderedParser
- YARD::Parser::ParserSyntaxError
- YARD::Parser::Ruby
- YARD::Parser::Ruby::AstNode
- YARD::Parser::Ruby::ClassNode
- YARD::Parser::Ruby::CommentNode
- YARD::Parser::Ruby::ConditionalNode
- YARD::Parser::Ruby::KeywordNode
- YARD::Parser::Ruby::Legacy
- YARD::Parser::Ruby::Legacy::RubyLex
- YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
- YARD::Parser::Ruby::Legacy::RubyParser
- YARD::Parser::Ruby::Legacy::RubyToken
- YARD::Parser::Ruby::Legacy::RubyToken::TkBlockContents
- YARD::Parser::Ruby::Legacy::RubyToken::TkError
- YARD::Parser::Ruby::Legacy::RubyToken::TkId
- YARD::Parser::Ruby::Legacy::RubyToken::TkKW
- YARD::Parser::Ruby::Legacy::RubyToken::TkNode
- YARD::Parser::Ruby::Legacy::RubyToken::TkOPASGN
- YARD::Parser::Ruby::Legacy::RubyToken::TkOp
- YARD::Parser::Ruby::Legacy::RubyToken::TkStatementEnd
- YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar
- YARD::Parser::Ruby::Legacy::RubyToken::TkVal
- YARD::Parser::Ruby::Legacy::RubyToken::TkWhitespace
- YARD::Parser::Ruby::Legacy::RubyToken::Token
- YARD::Parser::Ruby::Legacy::Statement
- YARD::Parser::Ruby::Legacy::StatementList
- YARD::Parser::Ruby::Legacy::TokenList
- YARD::Parser::Ruby::LiteralNode
- YARD::Parser::Ruby::LoopNode
- YARD::Parser::Ruby::MethodCallNode
- YARD::Parser::Ruby::MethodDefinitionNode
- YARD::Parser::Ruby::ModuleNode
- YARD::Parser::Ruby::ParameterNode
- YARD::Parser::Ruby::ReferenceNode
- YARD::Parser::Ruby::RipperParser
- YARD::Parser::Ruby::RubyParser
- YARD::Parser::SourceParser
- YARD::Parser::UndocumentableError
- YARD::Rake
- YARD::Rake::YardocTask
- YARD::Registry
- YARD::RegistryStore
- YARD::Serializers
- YARD::Serializers::Base
- YARD::Serializers::FileSystemSerializer
- YARD::Serializers::ProcessSerializer
- YARD::Serializers::StdoutSerializer
- YARD::Serializers::YardocSerializer
- YARD::Server
- YARD::Server::Adapter
- YARD::Server::Commands
- YARD::Server::Commands::Base
- YARD::Server::Commands::DisplayFileCommand
- YARD::Server::Commands::DisplayObjectCommand
- YARD::Server::Commands::FramesCommand
- YARD::Server::Commands::LibraryCommand
- YARD::Server::Commands::LibraryIndexCommand
- YARD::Server::Commands::LibraryOptions
- YARD::Server::Commands::ListCommand
- YARD::Server::Commands::SearchCommand
- YARD::Server::Commands::StaticFileCommand
- YARD::Server::DocServerHelper
- YARD::Server::DocServerSerializer
- YARD::Server::FinishRequest
- YARD::Server::LibraryNotPreparedError
- YARD::Server::LibraryVersion
- YARD::Server::NotFoundError
- YARD::Server::RackAdapter
- YARD::Server::RackMiddleware
- YARD::Server::Router
- YARD::Server::StaticCaching
- YARD::Server::WebrickAdapter
- YARD::Server::WebrickServlet
- YARD::StubProxy
- YARD::Tags
- YARD::Tags::AttributeDirective
- YARD::Tags::DefaultFactory
- YARD::Tags::DefaultTag
- YARD::Tags::Directive
- YARD::Tags::EndGroupDirective
- YARD::Tags::GroupDirective
- YARD::Tags::Library
- YARD::Tags::MacroDirective
- YARD::Tags::MethodDirective
- YARD::Tags::OptionTag
- YARD::Tags::OverloadTag
- YARD::Tags::ParseDirective
- YARD::Tags::RefTag
- YARD::Tags::RefTagList
- YARD::Tags::ScopeDirective
- YARD::Tags::Tag
- YARD::Tags::TagFormatError
- YARD::Tags::VisibilityDirective
- YARD::Templates
- YARD::Templates::Engine
- YARD::Templates::ErbCache
- YARD::Templates::Helpers
- YARD::Templates::Helpers::BaseHelper
- YARD::Templates::Helpers::FilterHelper
- YARD::Templates::Helpers::HtmlHelper
- YARD::Templates::Helpers::HtmlSyntaxHighlightHelper
- YARD::Templates::Helpers::Markup
- YARD::Templates::Helpers::Markup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::Markup::RDocMarkup::RDocMarkupToHtml
- YARD::Templates::Helpers::MarkupHelper
- YARD::Templates::Helpers::MethodHelper
- YARD::Templates::Helpers::ModuleHelper
- YARD::Templates::Helpers::TextHelper
- YARD::Templates::Helpers::UMLHelper
- YARD::Templates::Section
- YARD::Templates::Template
- YARD::Templates::Template::ClassMethods
- YARD::Templates::TemplateOptions
- YARD::Verifier
- Gem
- Gem::DocManager
- Gem::SourceIndex
- Gem::Specification
- Rack
- Rack::Request
- WEBrick
- WEBrick::HTTPRequest
- Array
- File
- Hash
- Insertion
- Module
- Object
- String
- SymbolHash

No matching classes.

# YARD::CLI::Yardoc

Yardoc is the default YARD CLI command (+yard doc+ and historic `yardoc` executable) used to generate and output (mainly) HTML documentation given a set of source files.

## Usage

Main usage for this command is:

    $ yardoc [options] [source_files [- extra_files]]

See +yardoc --help+ for details on valid options.

## Options File (`.yardopts`)

If a `.yardopts` file is found in the source directory being processed, YARD will use the contents of the file as arguments to the command, treating newlines as spaces. You can use shell-style quotations to group space delimited arguments, just like on the command line.

A valid `.yardopts` file might look like:

    --no-private
    --title "My Title"
    --exclude foo --exclude bar
    lib/**/*.erb
    lib/**/*.rb -
    HACKING.rdoc LEGAL COPYRIGHT

Note that Yardoc also supports the legacy RDoc style `.document` file, though this file can only specify source globs to parse, not options.

## Queries (`--query`)

Yardoc supports queries to select specific code objects for which to generate documentation. For example, you might want to generate documentation only for your public API. If you've documented your public methods with +@api public+, you can use the following query to select all of these objects:

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

Note that the syntax for queries is mostly Ruby with a few syntactic simplifications for meta-data tags. See the {Verifier} class for an overview of this syntax.

## Adding Custom Ad-Hoc Meta-data Tags (`--tag`)

YARD allows specification of {file:docs/Tags.md meta-data tags} programmatically via the {YARD::Tags::Library} class, but often this is not practical for users writing documentation. To make adding custom tags easier, Yardoc has a few command-line switches for creating basic tags and displaying them in generated HTML output.

To specify a custom tag to be displayed in output, use any of the following:

- `--tag` TAG:TITLE

- `--name-tag` TAG:TITLE

- `--type-tag` TAG:TITLE

- `--type-name-tag` TAG:TITLE

- `--title-tag` TAG:TITLE

"TAG:TITLE" is of the form: name:"Display Title", for example:

    --tag overload:"Overloaded Method"

See +yardoc --help+ for a description of the various options.

Tags added in this way are automatically displayed in output. To add a meta-data tag that does not show up in output, use +--hide-tag TAG+. Note that you can also use this option on existing tags to hide builtin tags, for instance.

## Processed Data Storage (`.yardoc` directory)

When Yardoc parses a source directory, it creates a `.yardoc` directory (by default, override with `-b`) at the root of the project. This directory contains marshal dumps for all raw object data in the source, so that you can access it later for various commands (`stats`, `graph`, etc.). This directory is also used as a cache for any future calls to `yardoc` so as to process only the files which have changed since the last call.

When Yardoc uses the cache in subsequent calls to `yardoc`, methods or classes that have been deleted from source since the last parsing will not be erased from the cache (YARD never deletes objects). In such a case, you should wipe the cache and do a clean parsing of the source tree. You can do this by deleting the `.yardoc` directory manually, or running Yardoc without `--use-cache` (`-c`).

@since 0.2.1 @see Verifier

### Constants

DEFAULT_YARDOPTS_FILE

  The configuration filename to load extra options from

### Attributes

apis[RW]

Keep track of which APIs are to be shown @return [Array<String>] a list of APIs @since 0.8.1

assets[RW]

@return [Array<String>] a list of assets to copy after generation @since 0.6.0

excluded[RW]

@return [Array<String>] list of excluded paths (regexp matches) @since 0.5.3

files[RW]

@return [Array<String>] list of Ruby source files to process

generate[RW]

@return [Boolean] whether to generate output

has_markup[RW]

@return [Boolean] whether markup option was specified @since 0.7.0

hidden_tags[RW]

@return [Array<Symbol>] a list of tags to hide from templates @since 0.6.0

list[RW]

@return [Boolean] whether to print a list of objects @since 0.5.5

options[R]

@return [Hash] the hash of options passed to the template. @see Templates::Engine#render

options_file[RW]

The options file name (defaults to {DEFAULT_YARDOPTS_FILE}) @return [String] the filename to load extra options from

save_yardoc[RW]

@return [Boolean] whether objects should be serialized to .yardoc db

statistics[RW]

@return [Boolean] whether to print statistics after parsing @since 0.6.0

use_cache[RW]

@return [Boolean] whether to use the existing yardoc db if the

    .yardoc already exists. Also makes use of file checksums to
    parse only changed files.

use_document_file[RW]

@return [Boolean] whether to parse options from .document

use_yardopts_file[RW]

@return [Boolean] whether to parse options from .yardopts

visibilities[RW]

Keep track of which visibilities are to be shown @return [Array<Symbol>] a list of visibilities @since 0.5.6

### Public Class Methods

new() click to toggle source

Creates a new instance of the commandline utility

    # File lib/yard/cli/yardoc.rb, line 208
    def initialize
      super
      @options = YardocOptions.new
      @options.reset_defaults
      @visibilities = [:public]
      @apis = []
      @assets = {}
      @excluded = []
      @files = []
      @hidden_tags = []
      @use_cache = false
      @use_yardopts_file = true
      @use_document_file = true
      @generate = true
      @options_file = DEFAULT_YARDOPTS_FILE
      @statistics = true
      @list = false
      @save_yardoc = true
      @has_markup = false

      if defined?(::Encoding) && ::Encoding.respond_to?(:default_external=)
        ::Encoding.default_external, ::Encoding.default_internal = 'utf-8', 'utf-8'
      end
    end

### Public Instance Methods

all_objects() click to toggle source

The list of all objects to process. Override this method to change which objects YARD should generate documentation for.

@deprecated To hide methods use the +@private+ tag instead. @return [Array<CodeObjects::Base>] a list of code objects to process

    # File lib/yard/cli/yardoc.rb, line 321
    def all_objects
      Registry.all(:root, :module, :class)
    end

description() click to toggle source

    # File lib/yard/cli/yardoc.rb, line 233
    def description
      "Generates documentation"
    end

parse_arguments(*args) click to toggle source

Parses commandline arguments @param [Array<String>] args the list of arguments @return [Boolean] whether or not arguments are valid @since 0.5.6

    # File lib/yard/cli/yardoc.rb, line 281
    def parse_arguments(*args)
      parse_yardopts_options(*args)

      # Parse files and then command line arguments
      optparse(*support_rdoc_document_file!) if use_document_file
      optparse(*yardopts) if use_yardopts_file
      optparse(*args)

      # Last minute modifications
      self.files = ['{lib,app}/**/*.rb', 'ext/**/*.c'] if self.files.empty?
      self.files.delete_if {|x| x =~ /\A\s*\Z/ } # remove empty ones
      readme = Dir.glob('README*').first
      readme ||= Dir.glob(files.first).first if options.onefile
      options.readme ||= CodeObjects::ExtraFileObject.new(readme) if readme
      options.files.unshift(options.readme).uniq! if options.readme

      Tags::Library.visible_tags -= hidden_tags
      add_visibility_verifier
      add_api_verifier

      # US-ASCII is invalid encoding for onefile
      if defined?(::Encoding) && options.onefile
        if ::Encoding.default_internal == ::Encoding::US_ASCII
          log.warn "--one-file is not compatible with US-ASCII encoding, using ASCII-8BIT"
          ::Encoding.default_external, ::Encoding.default_internal = ['ascii-8bit'] * 2
        end
      end

      if generate && !verify_markup_options
        false
      else
        true
      end
    end

run(*args) click to toggle source

Runs the commandline utility, parsing arguments and generating output if set.

@param [Array<String>] args the list of arguments. If the list only

    contains a single nil value, skip calling of {#parse_arguments}

@return [void]

    # File lib/yard/cli/yardoc.rb, line 243
    def run(*args)
      log.show_progress = true
      if args.size == 0 || !args.first.nil?
        # fail early if arguments are not valid
        return unless parse_arguments(*args)
      end

      checksums = nil
      if use_cache
        Registry.load
        checksums = Registry.checksums.dup
      end
      YARD.parse(files, excluded)
      Registry.save(use_cache) if save_yardoc

      if generate
        run_generate(checksums)
        copy_assets
      elsif list
        print_list
      end

      if !list && statistics && log.level < Logger::ERROR
        Registry.load_all
        log.enter_level(Logger::ERROR) do
          Stats.new(false).run(*args)
        end
      end

      true
    ensure
      log.show_progress = false
    end

yardopts() click to toggle source

Parses the .yardopts file for default yard options @return [Array<String>] an array of options parsed from .yardopts

    # File lib/yard/cli/yardoc.rb, line 327
    def yardopts
      return [] unless use_yardopts_file
      File.read_binary(options_file).shell_split
    rescue Errno::ENOENT
      []
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.