tosch · March 15, 2013 15:01 · Mar 15, 2013
diff --git a/yard_example.rb b/yard_example.rb
@@ -0,0 +1,130 @@
+# This is a very shallow example class for Yard.
+#
+# @abstract Subclass and override {#abstract_method} to implement a custom YardExample class.
+class AbstractYardExample
+  # This is something abstract.
+  # 
+  # @raise [NotImplementedError] if not overridden in subclass
+  def abstract_method
+    raise NotImplementedError
+  end
+end
+
+# Exception which may raised by {YardExample#find_comment_by_title}
+class CommentNotFoundError < StandardError; end
+
+# A stupid class that shows some Yard tags and their usage.
+#
+# @!attribute [r] comments
+#   @return [Array] all comments
+# @!attribute [rw] filter_method
+#   @param [:all, :without_text] filter_method the filter method to use.
+#   @return [:all, :without_text] the currently used filter method
+# @!attribute [w] writable
+#   @param [Boolean] writeable whether this is writable
+class YardExample < AbstractYardExample
+  attr_reader :comments
+  attr_accessor :filter_method
+  attr_writer :writable
+
+  include Enumerable
+
+  def initialize
+    @comments = []
+  end
+
+  # Filter the comments
+  #
+  # @return [Array] comments filtered by filter_method
+  def filtered_comments
+  end
+
+  # Adds a comment to the example.
+  #
+  # @example Add comment at the top of the list.
+  #   comment = Comment.new(:title => 'First Comment')
+  #   example = YardExample.new
+  #   example.add_comment(comment, position: :top)
+  # 
+  # @param comment [Comment] the comment to add
+  # @option options [Fixnum, :top, :bottom] :position (:bottom) position at which the comment shall be added
+  def add_comment(comment, options = {})
+  end
+
+  # @overload change_comment(old_title, new_attributes)
+  #   Modifies the comment given by the old_title.
+  #   @param title [String] the old title of the comment that shall be changed
+  #   @option new_attributes [String] :title the new title. If not set, the title won't be changed.
+  #   @option new_attributes [String] :text the new text. If not set, the text won't be changed.
+  # @overload change_comment(position, new_attributes)
+  #   Modifies the comment at the given position.
+  #   @param position [Fixnum] The position in the comments array
+  #   @option new_attributes [String] :title the new title. If not set, the title won't be changed.
+  #   @option new_attributes [String] :text the new text. If not set, the text won't be changed.
+  # @overload change_comment(new_attributes)
+  #   Modifies the first comment.
+  #   @option new_attributes [String] :title the new title. If not set, the title won't be changed.
+  #   @option new_attributes [String] :text the new text. If not set, the text won't be changed.
+  def change_comment(*args)
+  end
+
+  # Finds a comment by its title. Only returns the first match.
+  #
+  # @param title [String] the title to look for.
+  # @raise [CommentNotFoundError] if there is no comment with the given title
+  # @return [Comment] the comment which has title
+  def find_comment_by_title(title)
+    find { |comment| comment.title == title } || raise(CommentNotFoundError.new("Cannot find comment with title '#{title}'"))
+  end
+
+  # Yields comment after comment to the block given.
+  #
+  # @yieldparam comment [Comment]
+  def each
+    @comments.each do |comment|
+      yield comment
+    end
+  end
+
+  # Example method which is deprecated. Once upon a time, it did complex calculations...
+  #
+  # @deprecated Don't use anymore!
+  def deprecated
+  end
+end
+
+# This class is heavily used by YardExample.
+#
+# @!attribute [rw] title
+#   @param [String] title the comment's title
+#   @return [String] the comment's title
+# @!attribute [rw] text
+#   @param [String, nil] text the comment's text
+#   @return [String, nil] the comment's text
+class Comment
+  attr_accessor :title, :text
+
+  # @option attributes [String] :title ('Title') the comment's title.
+  # @option attributes [String] :text the comment's text
+  def initializer(attributes = {})
+    @title = attributes[:title] || 'Title'
+    @text  = attributes[:text]
+  end
+
+  # Determine if there's text on this comment.
+  #
+  # @return [Boolean] true when text is present
+  def has_text?
+    @text && !@text.empty?
+  end
+
+  # Compare the ordering of comments.
+  #
+  # @param other [Comment]
+  # @return [-1] if this comment's title is before the other's
+  # @return [0] if the comment's titles are the same
+  # @return [1] if the this comment's title is after the other's
+  def <=>(other)
+    self.title <=> other.title
+  end
+end
diff --git a/yard_output.xhtml b/yard_output.xhtml