Documentation with RDoc and YARD

# frozen_string_literal: true

#--
# Copyright (c) Example Author
# Licensed under the MIT License.
#++

# Looks books up by author.
class AuthorIndex
  def initialize
    @titles = Hash.new { |hash, name| hash[name] = [] }
  end

  # Returns the titles of one author.
  def titles_by(name)
    @titles[name]
  end
end

# frozen_string_literal: true

module Shelf
  # The catalogue of books, guarded by a mutex.
  #
  # A Catalog stores books through a *store* object and exposes them through
  # Enumerable, so every Enumerable method works on it:
  #
  #   catalog = Shelf::Catalog.new
  #   catalog.add(book).add(other)
  #   catalog.map(&:title)
  #
  # == Stores
  #
  # Any object that responds to +all+ and +add+ can be used. The default is
  # Shelf::Store::Memory.
  #
  # == See also
  #
  # * Shelf::Store::Memory
  # * Shelf::Loan
  class Catalog
    include Enumerable

    # Creates an empty catalogue backed by +store+.
    def initialize(store: Shelf.config.store)
      @store = store
      @mutex = Thread::Mutex.new
    end

    # Adds +book+ to the catalogue.
    #
    # Returns the catalogue itself, so calls can be chained.
    def add(book)
      @mutex.synchronize { @store.add(book) }
      self
    end

    # :call-seq:
    #   each { |book| ... } -> catalog
    #   each                -> enumerator
    #
    # Yields every book, or returns an Enumerator when no block is given.
    def each(&block)
      return enum_for(:each) unless block

      @mutex.synchronize { @store.all }.each(&block)
      self
    end
  end
end

# Shelf::Catalog < Object

---
# Includes:
Enumerable (from rid)

(from rid)
---
The catalogue of books, guarded by a mutex.

A Catalog stores books through a **store** object and exposes them
through Enumerable, so every Enumerable method works on it:

    catalog = Shelf::Catalog.new
    catalog.add(book).add(other)
    catalog.map(&:title)

## Stores

Any object that responds to `all` and `add` can be used. The default is
Shelf::Store::Memory.

## See also

*   Shelf::Store::Memory
*   Shelf::Loan
---
# Class methods:

    new

# Instance methods:

    add
    each

# Shelf::Catalog#each

(from rid)
### Implementation from Catalog
---
    each { |book| ... } -> catalog
    each                -> enumerator

---

Yields every book, or returns an Enumerator when no block is given.

= Shelf
== Borrowing

A *bold* word, an _italic_ word, a +monofont+ word and <tt>Hash#fetch(:a)</tt>.
A -- dash, (c) and "quotes" are converted. \Shelf::Catalog is not linked.

* a bullet
* another bullet
  continued on a second line

1. first step
2. second step

[isbn] a labelled item
title:: a same-line label

  def verbatim_code
    :kept_as_written
  end

See Shelf::Catalog#add, {the guide}[https://example.com/guide]
and Example[rdoc-ref:Shelf::Catalog].

<h1 id="label-Shelf">Shelf</h1>

<h2 id="label-Borrowing">Borrowing</h2>

<p>A <strong>bold</strong> word, an <em>italic</em> word, a <code>monofont</code> word and <code>Hash#fetch(:a)</code>. A – dash, © and “quotes” are converted. Shelf::Catalog is not linked.</p>
<ul><li>
<p>a bullet</p>
</li><li>
<p>another bullet continued on a second line</p>
</li></ul>
<ol><li>
<p>first step</p>
</li><li>
<p>second step</p>
</li></ol>
<dl class="rdoc-list label-list"><dt>isbn</dt>
<dd>
<p>a labelled item</p>
</dd></dl>
<dl class="rdoc-list note-list"><dt>title</dt>
<dd>
<p>a same-line label</p>
</dd></dl>

<pre><code>def verbatim_code
  :kept_as_written
end
</code></pre>

<p>See Shelf::Catalog#add, <a href="https://example.com/guide">the guide</a> and <a href="rdoc-ref:Shelf::Catalog">Example</a>.</p>

# frozen_string_literal: true

require "rdoc"

text = <<~RDOC
  = Loans

  A loan is *lent* or +overdue+.

  * lent
  * overdue
RDOC

html = RDoc::Markup::ToHtml.new(RDoc::Options.new).convert(text)
puts html

document = RDoc::Markup.parse(text)
puts document.parts.map { |part| part.class.name.split("::").last }.inspect
puts RDoc::VERSION

<h1 id="label-Loans"><a href="#label-Loans">Loans</a></h1>

<p>A loan is <strong>lent</strong> or <code>overdue</code>.</p>
<ul><li>
<p>lent</p>
</li><li>
<p>overdue</p>
</li></ul>
["Heading", "BlankLine", "Paragraph", "BlankLine", "List"]
7.0.4

$ rdoc --main README.md --title "Shelf 0.1.0" -o doc README.md lib

The following items are not documented:

In files:
* lib/shelf/catalog.rb
* lib/shelf/loan.rb
* lib/shelf/states.rb
* lib/shelf/store/memory.rb

  module Shelf
  end


In files:
* lib/shelf/store/memory.rb

  module Shelf::Store
  end



  Files:       4

  Classes:     3 (0 undocumented)
  Modules:     3 (2 undocumented)
  Constants:   2 (0 undocumented)
  Attributes:  2 (0 undocumented)
  Methods:    12 (0 undocumented)

  Total:      22 (2 undocumented)
   90.91% documented

The following items are not documented:

In files:
* lib/shelf/catalog.rb
* lib/shelf/loan.rb
* lib/shelf/states.rb
* lib/shelf/store/memory.rb

  module Shelf
  end


  class Shelf::Catalog # is documented

    # in file lib/shelf/catalog.rb:26
    # +store:Shelf.config.store+ is not documented
    def self.new(store: Shelf.config.store); end

    # in file lib/shelf/catalog.rb:44
    # +each->enumerator+ is not documented
    def each(&block); end

  end


  class Shelf::Loan # is documented

    # in file lib/shelf/loan.rb:30
    # +book+ is not documented
    def self.lent(book); end

    # in file lib/shelf/loan.rb:22
    # +state::available+ is not documented
    def self.new(book, state: :available); end

    # in file lib/shelf/loan.rb:69
    # +book+ is not documented
    def each_lent(); end

  end


In files:
* lib/shelf/store/memory.rb

  module Shelf::Store
  end

---
encoding: UTF-8
static_path: []
rdoc_include: []
page_dir:
apply_default_exclude: true
autolink_excluded_words: []
canonical_root:
charset: UTF-8
class_module_path_prefix:
embed_mixins: false
exclude: []
file_path_prefix:
footer_content:
hyperlink_all: false
line_numbers: false
locale_dir: locale
locale_name:
main_page: README.md
markup: markdown
output_decoration: true
show_hash: false
skip_tests: true
tab_width: 8
template_stylesheets: []
title: Shelf 0.1.0
visibility: :public
warn_missing_rdoc_ref: true
webcvs:

# What to document
lib
README.md

# frozen_string_literal: true

require "rdoc/task"

RDoc::Task.new do |rdoc|
  rdoc.title = "Shelf 0.1.0"
  rdoc.main = "README.md"
  rdoc.rdoc_dir = "doc"
  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
  rdoc.options << "--visibility" << "public"
end

rake clobber_rdoc   # Remove RDoc HTML files
rake rdoc           # Build RDoc HTML files
rake rdoc:coverage  # Print RDoc coverage report
rake rerdoc         # Rebuild RDoc HTML files

Rakefile:3: warning: rdoc/task is found in rdoc, which is not part of the default gems since Ruby 4.0.0.
You can add rdoc to your Gemfile or gemspec to fix this error.
rake aborted!
LoadError: cannot load such file -- rdoc/task (LoadError)

# frozen_string_literal: true

source "https://rubygems.org"

gemspec

gem "rake", "~> 13.0"
gem "rdoc", "~> 7.0", require: false

# frozen_string_literal: true

module Shelf
  # A book with an endless method.
  class Edition
    # Returns the label.
    def label = "second"
  end

  # A class that follows it.
  class Cover
    # Returns the colour.
    def colour
      "red"
    end
  end
end

Shelf
Shelf::Edition
Shelf::Edition::Cover

$ RDOC_USE_PRISM_PARSER=1 rdoc -q --ri -o rid endless.rb
=========================================================================
RDoc is using the experimental Prism parser to generate the documentation
=========================================================================

Shelf
Shelf::Cover
Shelf::Edition

# frozen_string_literal: true

require "stringio"

# Reads titles, one per line.
class TitleReader
  # @param io [#each_line] any object that responds to `each_line`
  #   (an indented line continues the tag above it)
  # @return [Array<String>] the titles without line endings
  def titles(io)
    io.each_line.map(&:chomp)
  end
end

TitleReader.new.titles(StringIO.new("Dune\nEmma\n")) # => ["Dune", "Emma"]

# frozen_string_literal: true

module Shelf
  # The catalogue of books, guarded by a mutex.
  #
  # A catalogue stores books through a store object and exposes them through
  # `Enumerable`, so every `Enumerable` method works on it.
  #
  # @example Build a catalogue and list the titles
  #   catalog = Shelf::Catalog.new
  #   catalog.add(book).add(other)
  #   catalog.map(&:title) # => ["Dune", "Emma"]
  #
  # @see Shelf::Store::Memory
  # @since 0.1.0
  class Catalog
    include Enumerable

    # @param store [#all, #add] any object that responds to `all` and `add`
    def initialize(store: Shelf.config.store)
      @store = store
      @mutex = Thread::Mutex.new
    end

    # Adds a book to the catalogue.
    #
    # @param book [Shelf::Book] the book to add
    # @return [self] the catalogue, so calls can be chained
    # @raise [ArgumentError] if the book is nil
    def add(book)
      raise ArgumentError, "book must not be nil" if book.nil?

      @mutex.synchronize { @store.add(book) }
      self
    end

    # Yields every book in the catalogue.
    #
    # @yield [book] each book, in insertion order
    # @yieldparam book [Shelf::Book] the current book
    # @yieldreturn [void]
    # @return [Enumerator<Shelf::Book>] when no block is given
    # @return [self] when a block is given
    def each(&block)
      return enum_for(:each) unless block

      @mutex.synchronize { @store.all }.each(&block)
      self
    end

    # Looks a book up by title.
    #
    # @overload find_by_title(title)
    #   @param title [String] the exact title
    #   @return [Shelf::Book, nil] the first match, or nil
    # @overload find_by_title(title, ignore_case:)
    #   @param title [String] the title to match
    #   @param ignore_case [Boolean] compare without regard to case
    #   @return [Shelf::Book, nil] the first match, or nil
    def find_by_title(title, ignore_case: false)
      find do |book|
        ignore_case ? book.title.casecmp?(title) : book.title == title
      end
    end

    # Counts books by author.
    #
    # @param options [Hash] reporting options
    # @option options [Integer] :limit (10) the maximum number of authors
    # @option options [Boolean] :sort (true) sort by count, highest first
    # @return [Hash{String => Integer}] author name to number of books
    # @deprecated Use {#group_by} with `author.name` instead.
    def counts(options = {})
      limit = options.fetch(:limit, 10)
      map { |book| book.author.name }.tally.first(limit).to_h
    end

    # @api private
    # @todo Replace with a lock-free read.
    def snapshot
      @mutex.synchronize { @store.all }
    end
  end
end

# frozen_string_literal: true

# Copyright (c) Example Author
# Support code shared by the catalogue.
#-

# Looks books up by author.
class AuthorIndex
  # @return [Hash{String => Array<String>}] titles by author name
  attr_reader :titles

  def initialize
    @titles = Hash.new { |hash, name| hash[name] = [] }
  end
end

# frozen_string_literal: true

module Shelf
  # A loan whose state predicates are generated by a small DSL.
  class Loan
    # @return [Symbol] the current state
    attr_reader :state

    # @param state [Symbol] the initial state
    def initialize(state)
      @state = state
    end

    # Defines a predicate method for one state.
    #
    # @!macro [attach] state_predicate
    #   @!method $1?
    #   Returns true when the loan is in the `$1` state.
    #   @return [Boolean]
    # @param name [Symbol] the state name
    # @return [Symbol] the name of the generated method
    def self.state_predicate(name)
      define_method(:"#{name}?") { state == name }
    end

    state_predicate :lent
    state_predicate :overdue

    # @!group Queries

    # @return [Boolean] whether the book is out
    def out?
      lent? || overdue?
    end

    # @!endgroup
  end
end

loan = Shelf::Loan.new(:lent)
loan.lent? # => true
loan.out? # => true

--markup markdown
--no-private
--protected
--output-dir doc
--readme README.md
--title "Shelf 0.1.0"
lib/**/*.rb
-
CHANGELOG.md
LICENSE.txt

# frozen_string_literal: true

require "yard"

YARD::Rake::YardocTask.new(:yard) do |task|
  task.files = ["lib/**/*.rb"]
  task.options = ["--no-private"]
  task.stats_options = ["--list-undoc"]
end

# Shelf::Catalog#add

(from rid)
### Implementation from Catalog
---
    add(book)

---

Adds a book to the catalogue.

@param book [Shelf::Book] the book to add @return [self] the catalogue,
so calls can be chained @raise [ArgumentError] if the book is nil