代码文档

# This is the documentation for the class. It's amazing
# what they do with corrugated cardboard these days.
class CardboardBox

# Turn a person into whatever they'd like to be.
#
# @param [ Person ] person The human to transmogrify.
#
# @return [ Tiger ] The transmogrified result.
def transmogrify(person)

# @raise [ Errors::Validations ] If validation failed.
def validate!

private
# Documentation is optional here.
def do_something_obvious

# This is an internal-only method.
#
# @api private
def dont_call_me_from_outside

# Clear all stored data.
#
# @note This operation deletes data in the database.
# @todo Refactor this method for performance.
def erase_data!

# This is how we did things back in the day.
#
# @deprecated
def the_old_way

# This is the description of the method. Line wraps in the description
# should not be indented.
#
# @return [ Symbol ] For macros, wraps must be double-space indented
#   on the second, third, etc. lines.

# GOOD:
# @return [ Symbol ] The return value
def my_method
# BAD:
# @return [ Symbol ] The return value
#
def my_method
# BAD:
# @param [ Symbol ] foo The input value
#
#
# @return [ Symbol ] The return value
def my_method(foo)

# @param [ Symbol | String ] name Either a Symbol or a String.

# @param [ Array<Symbol> ] array An Array of symbols.

# @param [ Hash<Symbol, Integer> ] hash A Hash whose keys are Symbols,
#   and whose values are Integers.

# @param [ Array<Symbol | String> ] array An Array whose members must
#   be either Symbols or Strings.

# @return [ Array<Symbol, Integer, Integer> ] A 3-member Array whose first
#   element is a Symbol, and whose second and third elements are Integers.

# @param [ Array<Symbol> | Array<Hash> ] array An Array containing only
#   Symbols, or an Array containing only Hashes. The Array may not contain
#   a mix of Symbols and Hashes.

# @param [ Hash<Symbol, [ true | false ]> ] hash A Hash whose keys are Symbols,
#   and whose values are boolean values.

# @param [ :before | :after ] timing One of the Symbol values :before or :after.

# GOOD:
# @param [ true | false | nil ] bool A boolean or nil value.
# BAD:
# @param [ TrueClass | FalseClass | NilClass ] bool A boolean or nil value.
# @param [ Boolean ] bool A boolean value.

# @return [ self ] Returns the object itself.

# @param [ String... ] *items The list of items name(s) as Strings.
def buy_groceries(*items)

# BAD:
# @param [ Array<String> ] *items The list of items name(s) as Strings.
def buy_groceries(*items)
buy_groceries("Cheese", "Crackers", "Wine")
# OK:
# @param [ Array<String>... ] *arrays One or more arrays containing name parts.
def set_people_names(*arrays)
set_people_names(["Harlan", "Sanders"], ["Jane", "K", ""Doe"], ["Jim", "Beam"])

# @param [ Symbol..., Hash ] *args A list of names, followed by a hash
#   as the optional last arg.
def say_hello(*args)

# @param [ [ String | Symbol ]... ] *fields A splat of mixed Symbols and Strings.

# @param [ String ] query The search string
# @param [ Boolean ] :exact_match Whether to do an exact match
# @param [ Integer ] :results_per_page Number of results
def search(query, exact_match: false, results_per_page: 10)

# @param opts [ Hash<Symbol, Object> ] The optional hash argument(s).
# @option opts [ String | Array<String> ] :items The items(s) as Strings to include.
# @option opts [ Integer ] :limit An Integer denoting the limit.
def buy_groceries(opts = {})

# @param **kwargs The optional keyword argument(s).
# @option **kwargs [ String | Array<String> ] :items The items(s) as Strings to include.
# @option **kwargs [ Integer ] :limit An Integer denoting the limit.
def buy_groceries(**kwargs)

# @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
#   Must take the person, location, and weapon used. Must return true or false.
def whodunit
  yield(:mustard, :ballroom, :candlestick)
end

# @param &block The block.
# @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
#   Must take the person, location, and weapon used. Must return true or false.
def whodunit(&block)
  yield(:scarlet, :library, :rope)
end
# @param &block The block.
# @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.
#   Must take the person, location, and weapon used. Must return true or false.
def whodunit(&block)
  block.call(:plum, :kitchen, :pipe)
end

# @param &block The block.
# @yieldparam [ Symbol ] The person.
# @yieldparam [ Symbol ] The location.
# @yieldparam [ Symbol ] The weapon used.
# @yieldreturn [ true | false ] Whether the guess is correct.
def whodunit(&block)
  yield(:peacock, :conservatory, :wrench)
end

# @param [ Proc<Integer, Integer, Integer> ] my_proc Proc argument which must
#   take 3 integers and must return true or false whether the guess is valid.
def guess_three(my_proc)
  my_proc.call(42, 7, 88)
end