# Class: YARD::CLI::Yardoc

Inherits:
  YardoptsCommand
  - Object
  - Command
  - YardoptsCommand
  - YARD::CLI::Yardoc
  show all

Defined in:
  lib/yard/cli/yardoc.rb

## Overview

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 meta-data tags programmatically via the 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 `yard help doc` 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`).

See Also:

- Verifier

Since:

- 0.2.1

## Direct Known Subclasses

Display, I18n, Stats

## Instance Attribute Summary collapse

- #apis ⇒ Array<String>

  Keep track of which APIs are to be shown.

- #assets ⇒ Array<String>

  A list of assets to copy after generation.

- #excluded ⇒ Array<String>

  List of excluded paths (regexp matches).

- #fail_on_warning ⇒ Boolean

  Whether yard exits with error status code if a warning occurs.

- #files ⇒ Array<String>

  List of Ruby source files to process.

- #generate ⇒ Boolean

  Whether to generate output.

- #has_markup ⇒ Boolean

  Whether markup option was specified.

- #hidden_apis ⇒ Array<String>

  Keep track of which APIs are to be hidden.

- #hidden_tags ⇒ Array<Symbol>

  A list of tags to hide from templates.

- #list ⇒ Boolean

  Whether to print a list of objects.

- #options ⇒ Hash readonly

  The hash of options passed to the template.

- #save_yardoc ⇒ Boolean

  Whether objects should be serialized to .yardoc db.

- #statistics ⇒ Boolean

  Whether to print statistics after parsing.

- #use_cache ⇒ Boolean

  Whether to use the existing yardoc db if the .yardoc already exists.

- #visibilities ⇒ Array<Symbol>

  Keep track of which visibilities are to be shown.

## Instance Method Summary collapse

- #all_objects ⇒ Array<CodeObjects::Base> deprecated Deprecated.

  To hide methods use the `@private` tag instead.

- #description ⇒ Object
- #initialize ⇒ Yardoc constructor

  Creates a new instance of the commandline utility.

- #parse_arguments(*args) ⇒ Boolean

  Parses commandline arguments.

- #run(*args) ⇒ void

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

## Constructor Details

### #initialize ⇒ `Yardoc`

Creates a new instance of the commandline utility

Since:

- 0.2.1

    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232

    # File 'lib/yard/cli/yardoc.rb', line 207

    def initialize
      super
      @options = YardocOptions.new
      @options.reset_defaults
      @visibilities = [:public]
      @apis = []
      @hidden_apis = []
      @assets = {}
      @excluded = []
      @files = []
      @hidden_tags = []
      @use_cache = false
      @generate = true
      @statistics = true
      @list = false
      @save_yardoc = true
      @has_markup = false
      @fail_on_warning = false

      if defined?(::Encoding) && ::Encoding.respond_to?(:default_external=)
        utf8 = ::Encoding.find('utf-8')

        ::Encoding.default_external = utf8 unless ::Encoding.default_external == utf8
        ::Encoding.default_internal = utf8 unless ::Encoding.default_internal == utf8
      end
    end

## Instance Attribute Details

### #apis ⇒ `Array<String>`

Keep track of which APIs are to be shown

Returns:

- (`Array<String>`) —

  a list of APIs

Since:

- 0.8.1

    180
    181
    182

    # File 'lib/yard/cli/yardoc.rb', line 180

    def apis
      @apis
    end

### #assets ⇒ `Array<String>`

Returns a list of assets to copy after generation.

Returns:

- (`Array<String>`) —

  a list of assets to copy after generation

Since:

- 0.6.0

    197
    198
    199

    # File 'lib/yard/cli/yardoc.rb', line 197

    def assets
      @assets
    end

### #excluded ⇒ `Array<String>`

Returns list of excluded paths (regexp matches).

Returns:

- (`Array<String>`) —

  list of excluded paths (regexp matches)

Since:

- 0.5.3

    155
    156
    157

    # File 'lib/yard/cli/yardoc.rb', line 155

    def excluded
      @excluded
    end

### #fail_on_warning ⇒ `Boolean`

Returns whether yard exits with error status code if a warning occurs.

Returns:

- (`Boolean`) —

  whether yard exits with error status code if a warning occurs

Since:

- 0.2.1

    204
    205
    206

    # File 'lib/yard/cli/yardoc.rb', line 204

    def fail_on_warning
      @fail_on_warning
    end

### #files ⇒ `Array<String>`

Returns list of Ruby source files to process.

Returns:

- (`Array<String>`) —

  list of Ruby source files to process

Since:

- 0.2.1

    151
    152
    153

    # File 'lib/yard/cli/yardoc.rb', line 151

    def files
      @files
    end

### #generate ⇒ `Boolean`

Returns whether to generate output.

Returns:

- (`Boolean`) —

  whether to generate output

Since:

- 0.2.1

    166
    167
    168

    # File 'lib/yard/cli/yardoc.rb', line 166

    def generate
      @generate
    end

### #has_markup ⇒ `Boolean`

Returns whether markup option was specified.

Returns:

- (`Boolean`) —

  whether markup option was specified

Since:

- 0.7.0

    201
    202
    203

    # File 'lib/yard/cli/yardoc.rb', line 201

    def has_markup
      @has_markup
    end

### #hidden_apis ⇒ `Array<String>`

Keep track of which APIs are to be hidden

Returns:

- (`Array<String>`) —

  a list of APIs to be hidden

Since:

- 0.8.7

    185
    186
    187

    # File 'lib/yard/cli/yardoc.rb', line 185

    def hidden_apis
      @hidden_apis
    end

### #hidden_tags ⇒ `Array<Symbol>`

Returns a list of tags to hide from templates.

Returns:

- (`Array<Symbol>`) —

  a list of tags to hide from templates

Since:

- 0.6.0

    189
    190
    191

    # File 'lib/yard/cli/yardoc.rb', line 189

    def hidden_tags
      @hidden_tags
    end

### #list ⇒ `Boolean`

Returns whether to print a list of objects.

Returns:

- (`Boolean`) —

  whether to print a list of objects

Since:

- 0.5.5

    170
    171
    172

    # File 'lib/yard/cli/yardoc.rb', line 170

    def list
      @list
    end

### #options ⇒ `Hash` (readonly)

Returns the hash of options passed to the template.

Returns:

- (`Hash`) —

  the hash of options passed to the template.

See Also:

- Templates::Engine#render

Since:

- 0.2.1

    148
    149
    150

    # File 'lib/yard/cli/yardoc.rb', line 148

    def options
      @options
    end

### #save_yardoc ⇒ `Boolean`

Returns whether objects should be serialized to .yardoc db.

Returns:

- (`Boolean`) —

  whether objects should be serialized to .yardoc db

Since:

- 0.2.1

    163
    164
    165

    # File 'lib/yard/cli/yardoc.rb', line 163

    def save_yardoc
      @save_yardoc
    end

### #statistics ⇒ `Boolean`

Returns whether to print statistics after parsing.

Returns:

- (`Boolean`) —

  whether to print statistics after parsing

Since:

- 0.6.0

    193
    194
    195

    # File 'lib/yard/cli/yardoc.rb', line 193

    def statistics
      @statistics
    end

### #use_cache ⇒ `Boolean`

Returns whether to use the existing yardoc db if the .yardoc already exists. Also makes use of file checksums to parse only changed files.

Returns:

- (`Boolean`) —

  whether to use the existing yardoc db if the .yardoc already exists. Also makes use of file checksums to parse only changed files.

Since:

- 0.2.1

    160
    161
    162

    # File 'lib/yard/cli/yardoc.rb', line 160

    def use_cache
      @use_cache
    end

### #visibilities ⇒ `Array<Symbol>`

Keep track of which visibilities are to be shown

Returns:

- (`Array<Symbol>`) —

  a list of visibilities

Since:

- 0.5.6

    175
    176
    177

    # File 'lib/yard/cli/yardoc.rb', line 175

    def visibilities
      @visibilities
    end

## Instance Method Details

### #all_objects ⇒ `Array<CodeObjects::Base>`

Deprecated.

To hide methods use the `@private` tag instead.

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

Returns:

- (`Array<CodeObjects::Base>`) —

  a list of code objects to process

Since:

- 0.2.1

    330
    331
    332

    # File 'lib/yard/cli/yardoc.rb', line 330

    def all_objects
      Registry.all(:root, :module, :class)
    end

### #description ⇒ `Object`

Since:

- 0.2.1

    234
    235
    236

    # File 'lib/yard/cli/yardoc.rb', line 234

    def description
      "Generates documentation"
    end

### #parse_arguments(*args) ⇒ `Boolean`

Parses commandline arguments

Parameters:

- args (`Array<String>`) —

  the list of arguments

Returns:

- (`Boolean`) —

  whether or not arguments are valid

Since:

- 0.5.6

    291
    292
    293
    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323

    # File 'lib/yard/cli/yardoc.rb', line 291

    def parse_arguments(*args)
      super(*args)

      # Last minute modifications
      self.files = Parser::SourceParser::DEFAULT_PATH_GLOB if files.empty?
      files.delete_if {|x| x =~ /\A\s*\Z/ } # remove empty ones
      readme = Dir.glob('README{,*[^~]}').
        select {|f| extra_file_valid?(f)}.
        sort_by {|r| [r.count('.'), r.index('.'), r] }.first
      readme ||= Dir.glob(files.first).first if options.onefile && !files.empty?
      options.readme ||= CodeObjects::ExtraFileObject.new(readme) if readme && extra_file_valid?(readme)
      options.files.unshift(options.readme).uniq! if options.readme

      Tags::Library.visible_tags -= hidden_tags
      add_visibility_verifier
      add_api_verifier

      apply_locale

      # 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) ⇒ `void`

This method returns an undefined value.

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

Parameters:

- args (`Array<String>`) —

  the list of arguments. If the list only contains a single nil value, skip calling of #parse_arguments

Since:

- 0.2.1

    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    282
    283
    284
    285

    # File 'lib/yard/cli/yardoc.rb', line 244

    def run(*args)
      log.show_progress = true
      if args.empty? || !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

      if save_yardoc
        Registry.lock_for_writing do
          YARD.parse(files, excluded)
          Registry.save(use_cache)
        end
      else
        YARD.parse(files, excluded)
      end

      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

      abort if fail_on_warning && log.warned

      true
    ensure
      log.show_progress = false
    end