example_rdoc.rb

##
# === RDoc::Generator::Markdown example.
#
# This example employs various RDoc features to demonstrate
# generator output.
#
# ---
#
# Links:
#
#  1. {Project Home Page}[https://github.com/skatkov/rdoc-markdown)
#  2. {RDoc Documentation}[http://ruby-doc.org/stdlib-2.0.0/libdoc/rdoc/rdoc/RDoc/Markup.html]
#

##
# A mixin for waterfowl creatures.
module Waterfowl
  # Swimming helper.
  def swim
    puts "swimming around"
  end
end

##
# The base class for all birds.
class Bird
  ##
  # Produce some noise.
  #--
  # FIXME: maybe extract this to a base class +Animal+?
  #++
  def speak # :yields: text
    puts "generic tweeting"
    yield "tweet"
    yield "tweet"
  end

  # Fly somewhere.
  #
  # Flying is the most critical feature of birds.
  #
  # :args: direction, velocity
  #
  # :call-seq:
  #   Bird.fly(symbol, number) -> bool
  #   Bird.fly(string, number) -> bool
  #
  # = Example
  #
  #   fly(:south, 70)
  def fly(direction, velocity)
    _fly_impl(direction, velocity)
  end

  def _fly_impl(_direction, _velocity) # :nodoc:
    puts "flying away: direction=#{direction}, velocity=#{velocity}"
  end
end

##
# A duck is a Waterfowl Bird.
#
# Features:
#
#  bird::
#
#    * speak
#    * fly
#
#  waterfowl::
#
#    * swim
class Duck
  extend Animal
  include Waterfowl

  # :section: Bird overrides

  # Duck overrides generic implementation.
  def speak
    speech = quack
    yield speech
  end

  # Implements quacking
  def quack
    "quack"
  end

  private :quack

  # :section: Duck extensions

  # True for domestic ducks.
  attr_accessor :domestic

  # True for rubber ducks.
  attr_reader :rubber

  MAX_VELOCITY = 130 # Maximum velocity for a flying duck.

  ##
  # Global list of all rubber ducks.
  #
  # Use when in trouble.
  @@rubber_ducks = []

  # @return [Array<Duck>] list of all rubber ducks
  def self.rubber_ducks
    @@rubber_ducks
  end

  # Creates a new duck.
  #
  # @param [Boolean] domestic
  # @param [Boolean] rubber
  def initialize(domestic, rubber)
    @domestic = domestic
    @rubber = rubber
    @@rubber_ducks << self if rubber
  end

  # Checks if this duck is a useful one.
  #
  # :call-seq:
  #   Bird.useful? -> bool
  def useful?
    @domestic || @rubber
  end
end

# Default velocity for a flying duck.
DEFAULT_DUCK_VELOCITY = 70
DEFAULT_SPEED = 10 # Maximum speed for a swimming duck.


# Default rubber duck.
#
# *Note:*
#  Global variables are evil, but rubber ducks are worth it.
$default_rubber_duck = Duck.new(false, true)

# Domestic rubber duck.
#
# *Note:*
#  This is weird... Thus not making it global.
domestic_rubber_duck = Duck.new(true, true) # rubocop:disable Lint/UselessAssignment