Why are methods in Ruby documentation preceded by a hash sign?

Note that the convention is:

Class#method

rather than

object#method

In code you would have object.method, if object was an instance of class. The # convention is not used in code.

From the RDoc documentation:

Use :: for describing class methods, # for describing instance methods, and use . for example code.

The # notation is used to refer to the canonical instance method, like String#upcase. The . notation is used to refer to the method of a particular instance, like mystring.upcase. The distinction is made to not imply that a class method 'upcase' exists.

From the rdoc docs (emphasis mine):

Names of classes, source files, and any method names containing an underscore or preceded by a hash character are automatically hyperlinked from comment text to their description.

All the answers above you list are correct. The one thing I would add is that the documentation style you said you would perfer

Class.method

would be easily confused with class methods. Since you can call class methods in ruby using the above syntax:

class Foo
  def self.say_hi
    puts "hi"
  end
end

Foo.say_hi    # => prints "hi"

The hash notation was introduced "Programming Ruby - The Pragmatic Programmer's Guide" first published in December 2000.

The "Preface" contains "Notational Conventions":

Within the text, Fred#doIt is a reference to an instance method (doIt) of class Fred, while Fred.new [In some other Ruby documentation, you may see class methods written as Fred::new. This is perfectly valid Ruby syntax; we just happen to feel that Fred.new is less distracting to read.] is a class method, and Fred::EOF is a class constant.

This is clarified in the 2nd edition, published in October 2004:

Within the text, Fred#do_something is a reference to an instance method (in this case do_something) of class Fred, Fred.new is a class method, and Fred::EOF is a class constant. The decision to use a hash character to indicate instance methods was a tough one: it isn’t valid Ruby syntax, but we thought that it was important to differentiate between the instance and class methods of a particular class. When you see us write File.read, you know we’re talking about the class method read. When instead we write File#read, we’re referring to the instance method read.

Ruby itself uses this notation:

> rvm use 1.9.3
Using ruby-1.9.3-p551

> Object.instance_method(:initialize)
=> #<UnboundMethod: Object(BasicObject)#initialize>

It was introduced and formalised by Matz in February 2002:

commit 8210c254bee19294af67bcee0e8f5e02ebb39a60
Author: matz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date:   Tue Feb 5 07:56:31 2002 +0000

    * io.c (fptr_finalize): should raise error when fclose fails.

    * eval.c (method_inspect): proper output format to distinguish
      methods and singleton methods.


    git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@2046 b2dd03c8-39d4-4d8f-98ff-823fe69b080e