In ruby, use `.` or `::` for class method documentation and comments?-CodePudding

Both . and :: can be used to call class methods, but, in my experience, . is by far the most commonly used of the two. So I am accustomed to using that form in documentation and RSpec describe/context/expect strings.

However, the Ruby API documentation uses :: (e.g. at

Note: This is not a duplicate of Is there a difference between :: and . when calling class methods in Ruby?. That question refers to the use of the two alternate notations in Ruby source code, whereas this question refers to documentation and other textual descriptions (e.g. in rspec strings). There may be reasons to make different choices in code vs. documentation, for example, that using . in code more clearly indicates a message call vs. a constant access, whereas in documentation :: might be preferred to more dramatically distinguish class methods from instance methods.

CodePudding user response：

As far as I know RuboCop always suggets to use . when calling class method, as explained here.

Looking at documentation you have linked regarding the class String, they seem to use a single . when calling class methods, as seen here.

Actually I was not able to find a code snippet in that doc page that uses the :: notation for calling a class method.

If you are referring to the menu on the left, which uses :: to indicate class methods and # for instance methods, it's a Ruby documentation convention and has no real meaning in actual code.

Maybe this could be an helpful resource.

CodePudding user response：

In Ruby, it is recommended to use the :: notation for documenting and commenting on class methods. This is because the :: notation is more explicit and clear about the scope of the method, and it makes it easier to distinguish between class and instance methods.

For example, consider the following class and method:

class MyClass
  # This is a class method
  def self.my_method
    # Method implementation goes here
  end
end

To document or comment on the my_method class method, you can use the :: notation as follows:

class MyClass
  # This is a class method
  def self.my_method
    # Method implementation goes here
  end

  # This is the documentation for the MyClass::my_method class method
  # @return [String] The result of the method
  def self.my_method_documentation
    # Documentation goes here
  end
end

Alternatively, you could use the . notation as follows:

class MyClass
  # This is a class method
  def self.my_method
    # Method implementation goes here
  end

  # This is the documentation for the MyClass.my_method class method
  # @return [String] The result of the method
  def self.my_method_documentation
    # Documentation goes here
  end
end

However, using the :: notation is generally considered to be clearer and more explicit, especially when documenting or commenting on complex or nested class hierarchies. Additionally, using the :: notation can help to avoid confusion with instance methods, which are defined using the . notation.