Description of Examples

[maasha]

I would like to add some lines of description to each example in the Examples section, however, that seems to violate the format, and the description becomes an example of its own :o(. One way to deal with this is to include the description as a comment in the example like the return value, but the description is not part of the code - and it makes the HTML less readable.

# Public: Outputs 'Hello World!' to $stdout.
#
# Examples
#
# This is my description.
#
#   hello_world
#   # => 'Hello World!'
#
# Returns nil.

[maasha]

Another related question: how do you express that a particular example raises?

# Method that raises if options include any option not in the allowed Array.
#
# options - The Hash with options to be checked.
# allowed - One or more allowed options.
#
# Examples
#
#   options_allowed({foo: "bar"}, :foo)
#   # => nil
#
#   options_allowed({foo: "bar"}, :foobar)
#   # => Raises ???
#
# Returns nothing.
# Raises OptionError on any options not in the allowed Array.