YARD Cheatsheet

document.rb

# Represents a generic document in a document management system.
# @abstract
# @author John Doe
# @since 1.0.0
# @deprecated Use NewDocument instead.
class Document  
  # @!attribute [r] title
  #   @return [String]
  attr_reader :title

  # @!attribute [w] description
  #   @return [String]
  attr_writer :description
  
  # @!attribute [rw] sections
  #   @api private
  #   @return [Array<Section>]
  attr_accessor :sections
  
  # Initializes a new Document instance.
  # @note This method should be called with care.
  #
  # @param title [String] the title of the document
  # @param description [String] the description of the document
  # @param options [Hash] additional configuration options
  # @option options [Boolean] :editable whether the document can be edited
  # @yieldparam [String] content The content of the document.
  # @yieldreturn [String] Returns a modified content.
  #
  # @raise [ArgumentError] if the title is nil
  #
  # @return [Document] a new Document instance
  def initialize(title, description, options = {})
    raise ArgumentError, "Title cannot be nil" unless title
    
    @title       = title
    @description = description
    @editable    = options.fetch(:editable, true)
    
    @content = yield(content) if block_given?
  end

  # Edits the document content.
  #
  # @overload edit(new_content)
  #   @param new_content [String] the new content for the document
  #   @return [Boolean] true if editing was successful, false otherwise
  #   
  # @overload edit
  #   @yield Gives a block to process the current content.
  #   @yieldreturn [String] Returns the new content after processing.
  #   @return [Boolean] true if editing was successful, false otherwise
  #
  # @deprecated Use `modify` method instead.
  def edit(new_content = nil)
    if new_content
      @content = new_content
      true
    elsif block_given?
      @content = yield(@content)
      true
    else
      false
    end
  end
  
  # @todo Implement a proper save mechanism
  def save
    # Implementation pending
  end

  # Views the document
  #
  # @example Viewing the document title
  #   document.view_title #=> "Sample Document"
  #
  # @see #edit
  # @return [String] the title of the document
  def view_title
    @title
  end
  
end