Adding Yard Tags into a template

README.md

@@ -31,4 +31,8 @@ This is a successor to [rdoc-mardown gem](https://github.com/skatkov/rdoc-markdo
 ## Testing
 Unit tests can't really test this gem properly. So it's semi-manual process of making changes and reviewing output.
 
-  `yardoc example.rb` -> outputs everything into example/ folder.
+Testing Rdoc conversion to markdown:
+  `yardoc example_rdoc.rb` -> outputs everything into example/ folder.
+
+Testing Yard conversion to markdown:
+  `yardoc example_yard.rb` -> outputs everything into example/ folder.

example/Aquatic.md

@@ -0,0 +1,20 @@
+# Module: Aquatic
+
+**Defined in:** example_yard.rb
+
+A mixin for aquatic creatures.
+
+# Public Instance Methods
+## swim() [](#method-i-swim)
+Swim in the water.
+
+**return** [void] 
+
+
+# Constants
+## DEFAULT_SALMON_SPEED [](#constant-DEFAULT_SALMON_SPEED)
+
+
+## MAX_DEPTH [](#constant-MAX_DEPTH)
+
+

example/Bird.md

@@ -1,7 +1,7 @@
 # Class: Bird
 **Inherits:** Object
 
-**Defined in:** example.rb
+**Defined in:** example_rdoc.rb
 
 The base class for all birds.
 
@@ -27,12 +27,15 @@ Flying is the most critical feature of birds.
 ## speak() [](#method-i-speak)
 Produce some noise. -- FIXME: maybe extract this to a base class `Animal`? ++
 
+**yield** ["tweet"] 
 
 
 # Constants
 ## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
 Default velocity for a flying duck.
 
+
 ## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
 Maximum speed for a swimming duck.
 
+

example/Duck.md

@@ -5,7 +5,7 @@
 
 **Includes:** Waterfowl
 
-**Defined in:** example.rb
+**Defined in:** example_rdoc.rb
 
 A duck is a Waterfowl Bird.
 
@@ -24,9 +24,13 @@ Features:
 ## initialize(domestic, rubber) [](#method-i-initialize)
 Creates a new duck.
 
+**param** [Boolean] 
+**param** [Boolean] 
+**return** [Duck] a new instance of Duck
 ## speak() [](#method-i-speak)
 Duck overrides generic implementation.
 
+**yield** [speech] 
 ## swim() [](#method-i-swim)
 Swimming helper.
 
@@ -36,9 +40,11 @@ Checks if this duck is a useful one.
 :call-seq:
     Bird.useful? -> bool
 
+**return** [Boolean] 
 
 # Public Class Methods
 ## rubber_ducks() [](#method-c-rubber_ducks)
+**return** [Array<Duck>] list of all rubber ducks
 
 # Attributes
 ## domestic[RW] [](#attribute-i-domestic)
@@ -52,6 +58,8 @@ True for rubber ducks.
 ## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
 Default velocity for a flying duck.
 
+
 ## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
 Maximum speed for a swimming duck.
 
+

example/Fish.md

@@ -0,0 +1,32 @@
+# Class: Fish
+**Inherits:** Object
+
+**Defined in:** example_yard.rb
+
+The base class for all fish.
+
+# Public Instance Methods
+## make_sound() [](#method-i-make_sound)
+Make a sound.
+
+**return** [void] 
+**yield** [sound] The sound produced by the fish
+**yieldparam** [String] The actual sound
+## swim(direction, speed) [](#method-i-swim)
+Swim in a specific direction.
+
+Swimming is the most critical feature of fish.
+
+**example** [] swim(:north, 30)
+**param** [Symbol, String] The direction to swim
+**param** [Integer] The speed at which to swim
+**return** [Boolean] Whether the swim was successful
+
+
+# Constants
+## DEFAULT_SALMON_SPEED [](#constant-DEFAULT_SALMON_SPEED)
+
+
+## MAX_DEPTH [](#constant-MAX_DEPTH)
+
+

example/Salmon.md

@@ -0,0 +1,58 @@
+# Class: Salmon
+**Inherits:** Fish
+
+**Includes:** Aquatic
+
+**Defined in:** example_yard.rb
+
+A salmon is an Aquatic Fish.
+
+## Features
+
+*   **Fish**
+    *   make_sound
+    *   swim
+*   **Aquatic**
+    *   swim (overridden)
+
+# Public Instance Methods
+## initialize(farmed, wild) [](#method-i-initialize)
+Creates a new salmon.
+
+**param** [Boolean] Whether the salmon is farmed
+**param** [Boolean] Whether the salmon is wild
+**return** [Salmon] a new instance of Salmon
+## make_sound() [](#method-i-make_sound)
+Salmon overrides generic implementation.
+
+**return** [void] 
+**yield** [sound] The sound produced by the salmon
+**yieldparam** [String] The actual sound
+## sustainable?() [](#method-i-sustainable?)
+Checks if this salmon is sustainable.
+
+**return** [Boolean] Whether the salmon is sustainable
+## swim() [](#method-i-swim)
+Swim in the water.
+
+**return** [void] 
+
+# Public Class Methods
+## wild_salmon() [](#method-c-wild_salmon)
+**return** [Array<Salmon>] List of all wild salmon
+
+# Attributes
+## farmed[RW] [](#attribute-i-farmed)
+
+**return** [Boolean] True for farmed salmon
+## wild[RW] [](#attribute-i-wild)
+
+**return** [Boolean] True for wild salmon
+
+# Constants
+## DEFAULT_SALMON_SPEED [](#constant-DEFAULT_SALMON_SPEED)
+
+
+## MAX_DEPTH [](#constant-MAX_DEPTH)
+
+

example/Waterfowl.md

@@ -1,6 +1,6 @@
 # Module: Waterfowl
 
-**Defined in:** example.rb
+**Defined in:** example_rdoc.rb
 
 A mixin for waterfowl creatures.
 
@@ -14,6 +14,8 @@ Swimming helper.
 ## DEFAULT_DUCK_VELOCITY [](#constant-DEFAULT_DUCK_VELOCITY)
 Default velocity for a flying duck.
 
+
 ## DEFAULT_SPEED [](#constant-DEFAULT_SPEED)
 Maximum speed for a swimming duck.
 
+

example/index.csv

@@ -1,17 +1,17 @@
 name,type,path
 Waterfowl,Module,Waterfowl.md
-Waterfowl#DEFAULT_DUCK_VELOCITY,Constant,Waterfowl.md#constant-DEFAULT_DUCK_VELOCITY
-Waterfowl#DEFAULT_SPEED,Constant,Waterfowl.md#constant-DEFAULT_SPEED
+Waterfowl.DEFAULT_DUCK_VELOCITY,Constant,Waterfowl.md#constant-DEFAULT_DUCK_VELOCITY
+Waterfowl.DEFAULT_SPEED,Constant,Waterfowl.md#constant-DEFAULT_SPEED
 Waterfowl.swim,Method,Waterfowl.md#method-i-swim
 Bird,Class,Bird.md
-Bird#DEFAULT_DUCK_VELOCITY,Constant,Bird.md#constant-DEFAULT_DUCK_VELOCITY
-Bird#DEFAULT_SPEED,Constant,Bird.md#constant-DEFAULT_SPEED
+Bird.DEFAULT_DUCK_VELOCITY,Constant,Bird.md#constant-DEFAULT_DUCK_VELOCITY
+Bird.DEFAULT_SPEED,Constant,Bird.md#constant-DEFAULT_SPEED
 Bird._fly_impl,Method,Bird.md#method-i-_fly_impl
 Bird.fly,Method,Bird.md#method-i-fly
 Bird.speak,Method,Bird.md#method-i-speak
 Duck,Class,Duck.md
-Duck#DEFAULT_DUCK_VELOCITY,Constant,Duck.md#constant-DEFAULT_DUCK_VELOCITY
-Duck#DEFAULT_SPEED,Constant,Duck.md#constant-DEFAULT_SPEED
+Duck.DEFAULT_DUCK_VELOCITY,Constant,Duck.md#constant-DEFAULT_DUCK_VELOCITY
+Duck.DEFAULT_SPEED,Constant,Duck.md#constant-DEFAULT_SPEED
 Duck.initialize,Method,Duck.md#method-i-initialize
 Duck.speak,Method,Duck.md#method-i-speak
 Duck.swim,Method,Duck.md#method-i-swim

example_yard.rb

@@ -0,0 +1,154 @@
+# @title YARD Markdown Example
+# @description This example demonstrates various YARD features using markdown formatting.
+#
+# ## Links
+#
+# 1. [YARD Documentation](https://yardoc.org/)
+# 2. [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax)
+
+# A mixin for aquatic creatures.
+module Aquatic
+  # Swim in the water.
+  #
+  # @return [void]
+  def swim
+    puts "swimming in the water"
+  end
+end
+
+# The base class for all fish.
+class Fish
+  # Make a sound.
+  #
+  # @yield [sound] The sound produced by the fish
+  # @yieldparam sound [String] The actual sound
+  # @return [void]
+  def make_sound
+    puts "generic bubbling"
+    yield "blub"
+    yield "blub"
+  end
+
+  # Swim in a specific direction.
+  #
+  # Swimming is the most critical feature of fish.
+  #
+  # @param direction [Symbol, String] The direction to swim
+  # @param speed [Integer] The speed at which to swim
+  # @return [Boolean] Whether the swim was successful
+  #
+  # @example
+  #   swim(:north, 30)
+  def swim(direction, speed)
+    _swim_impl(direction, speed)
+  end
+
+  private
+
+  # @!visibility private
+  def _swim_impl(direction, speed)
+    puts "swimming away: direction=#{direction}, speed=#{speed}"
+  end
+end
+
+# A salmon is an Aquatic Fish.
+#
+# ## Features
+#
+# - **Fish**
+#   - make_sound
+#   - swim
+# - **Aquatic**
+#   - swim (overridden)
+class Salmon < Fish
+  include Aquatic
+
+  # @!group Fish overrides
+
+  # Salmon overrides generic implementation.
+  #
+  # @yield [sound] The sound produced by the salmon
+  # @yieldparam sound [String] The actual sound
+  # @return [void]
+  def make_sound
+    sound = splash
+    yield sound
+  end
+
+  # Implements splashing
+  #
+  # @return [String] The splash sound
+  def splash
+    "splash"
+  end
+
+  private :splash
+
+  # @!endgroup
+
+  # @!group Salmon specific attributes
+
+  # @return [Boolean] True for farmed salmon
+  attr_accessor :farmed
+
+  # @return [Boolean] True for wild salmon
+  attr_reader :wild
+
+  # @return [Integer] Maximum speed for a swimming salmon
+  MAX_SPEED = 40
+
+  # @!endgroup
+
+  # Global list of all wild salmon.
+  #
+  # Use for conservation efforts.
+  @@wild_salmon = []
+
+  # @return [Array<Salmon>] List of all wild salmon
+  def self.wild_salmon
+    @@wild_salmon
+  end
+
+  # Creates a new salmon.
+  #
+  # @param farmed [Boolean] Whether the salmon is farmed
+  # @param wild [Boolean] Whether the salmon is wild
+  def initialize(farmed, wild)
+    @farmed = farmed
+    @wild = wild
+    @@wild_salmon << self if wild
+  end
+
+  # Checks if this salmon is sustainable.
+  #
+  # @return [Boolean] Whether the salmon is sustainable
+  def sustainable?
+    @wild || (@farmed && environmentally_friendly?)
+  end
+
+  private
+
+  # @return [Boolean] Whether farming practices are environmentally friendly
+  def environmentally_friendly?
+    # Implementation details...
+    true
+  end
+end
+
+# @!constant [Integer] DEFAULT_SALMON_SPEED
+#   Default speed for a swimming salmon
+DEFAULT_SALMON_SPEED = 20
+
+# @!constant [Integer] MAX_DEPTH
+#   Maximum depth for salmon habitat
+MAX_DEPTH = 500
+
+# Default wild salmon.
+#
+# @note Global variables should be used sparingly, but this is for demonstration.
+$default_wild_salmon = Salmon.new(false, true)
+
+# Farmed sustainable salmon.
+#
+# @note This is just a local variable for demonstration purposes.
+farmed_sustainable_salmon = Salmon.new(true, false)