Ruby Draft Specification

Currently, source code like this is not possible:

class Something
  class Foo

    def some_method
    end

    =begin
      This method is a dummy method.

      Parameters:
        baz: This is a dummy parameter.
    =end
    def bar(baz)
    end

    def some_other_method
    end
  end
end

instead of writing this, programmars are required to write this:

class Something
  class Foo

    def some_method
    end

=begin
      This method is a dummy method.

      Parameters:
        baz: This is a dummy parameter.
=end
    def bar(baz)
    end

    def some_other_method
    end
  end
end

Note that the "=begin" and "=end" tokens have to be at the beginning of the line. This distorts both the view and the process of writing and modifying the source code. Especially in cases where a whole block of text is indented by some space or tab offset, the resulting source code yields a syntax error.

This behaviour defeats many purposes of having multi-line-comments in the first place, and this behaviour is in conflict with the Principle Of Least Surprise.

This is why, in a standardized Ruby language, the restriction of having the "=begin" and "=end" tokens as the very first tokens of a line (without whitespace) should be relaxed, at least to allow whitespace between beginning of the line and the token. (Maybe more relaxation to allow "=begin" and "=end" at arbitrary locations within the source code should also be considered.)