Skip to content

Instantly share code, notes, and snippets.

@roberttravispierce
Forked from hunj/rdoc_example.rb
Created February 15, 2022 00:45
Show Gist options
  • Save roberttravispierce/448b41f539a7b58cb66ef8ddecf1f6ba to your computer and use it in GitHub Desktop.
Save roberttravispierce/448b41f539a7b58cb66ef8ddecf1f6ba to your computer and use it in GitHub Desktop.
Ruby RDoc Example
## Found in: http://blog.firsthand.ca/2010/09/ruby-rdoc-example.html
# * Style guide based on Rails documention
module Namespace #:nodoc: don't document this
# Generic Namespace exception class
class NamespaceError < StandardError
end
# Raised when...
class SpecificError < NamespaceError
end
# Document the responsibility of the class
#
# == Heading
#
# Use headings to break up descriptions
#
# == Formatting
#
# Embody +parameters+ or +options+ in Teletype Text tags. You can also use
# *bold* or *italics* but must use HTML tags for <b>multiple words</b>,
# <i>like this</i> and <tt>like this</tt>.
class Base
# RDOC documents constants as well
MAX_NUMBER_OF_BOOKINGS = 3
# Write comments above for accessors, this will be presented as [R/W]
attr_accessor :first_name
# However this one will be presented as [R]
attr_reader :name
def initialize(string) #:notnew: stops RDoc from seeing the initialize method as the new method
end
# Desribe the behaviour of the method
#
# ==== Attributes
#
# * +remove_string+ - Document the first attribute
# * +append_string+ - Document the second attribute
# * +options+ - Document the third attribute
#
# ==== Options
#
# You may which to break out options as a separate item since there maybe
# multiple items. Note options are prefixed with a colon, denoting them
# as a
#
# * +:conditions+ - An SQL fragment like "administrator = 1"
# * +:order+ - An SQL fragment like "created_at DESC, name".
# * +:group+ - An attribute name by which the result should be grouped
# * +:limit+ - An integer determining the limit on the number of rows that should be returned.
# * +:offset+ - An integer determining the offset from where the rows should be fetched.
# * +:joins+ - Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id" (rarely needed)
#
# ==== Examples
#
# Illustrate the behaviour of the method using examples. Indent examples:
#
# base = Base.new("Example String")
# base.method_name("Example", "more")
def method_name(remove_string, append_string, options)
end
end
end
# Examples from Active Record
module ActiveRecord #:nodoc:
# Generic Active Record exception class.
class ActiveRecordError < StandardError
end
# Raised when the single-table inheritance mechanism failes to locate the subclass
# (for example due to improper usage of column that +inheritance_column+ points to).
class SubclassNotFound < ActiveRecordError #:nodoc:
end
class Base
# A generic "counter updater" implementation, intended primarily to be
# used by increment_counter and decrement_counter, but which may also
# be useful on its own. It simply does a direct SQL update for the record
# with the given ID, altering the given hash of counters by the amount
# given by the corresponding value:
#
# ==== Attributes
#
# * +id+ - The id of the object you wish to update a counter on.
# * +counters+ - An Array of Hashes containing the names of the fields
# to update as keys and the amount to update the field by as values.
#
# ==== Examples
#
# # For the Post with id of 5, decrement the comment_count by 1, and
# # increment the action_count by 1
# Post.update_counters 5, :comment_count => -1, :action_count => 1
# # Executes the following SQL:
# # UPDATE posts
# # SET comment_count = comment_count - 1,
# # action_count = action_count + 1
# # WHERE id = 5
def update_counters(id, counters)
updates = counters.inject([]) { |list, (counter_name, increment)|
sign = increment < 0 ? "-" : "+"
list << "#{connection.quote_column_name(counter_name)} = #{connection.quote_column_name(counter_name)} #{sign} #{increment.abs}"
}.join(", ")
update_all(updates, "#{connection.quote_column_name(primary_key)} = #{quote_value(id)}")
end
end
end
- See more at: http://blog.firsthand.ca/2010/09/ruby-rdoc-example.html#sthash.gLbudQwO.dpuf
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment