0

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 https://rubyapi.org/3.1/o/string). Is that intended to mean that that form is preferred for the cases I described?

enter image description here

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.

Keith Bennett
  • 4,722
  • 1
  • 25
  • 35
  • See also https://stackoverflow.com/q/11043450/479863 and the duplicates listed there. – mu is too short Dec 03 '22 at 04:05
  • Please see the last paragraph of the question (which I just added). The two are not the same. – Keith Bennett Dec 03 '22 at 04:57
  • 3
    One thing to keep in mind is that a lot of the docs for the Ruby core are truly ancient and may not actually reflect how the language is currently used and you'll very likely find inconsistencies in how this is done even there. What matters really is conventions that you have for your project. – max Dec 03 '22 at 13:10
  • 1
    There are no hard rules on documentation but I would lean towards documentation conventions being as close as possible to code conventions; so in documentation `C.m` would be a class method, `C::K` would be a constant, and `C#m` would be an instance method (this one only because that's how everyone does it). That's how yard does it (see https://rubydoc.info/github/rack/rack-attack/main/Rack/Attack for example) and that's close enough to "current standards" for me. – mu is too short Dec 03 '22 at 18:04
  • Noel Rappin, author of the most recent version of the authoritative Ruby Pickaxe book (https://pragprog.com/titles/ruby5/programming-ruby-3-2-5th-edition/), answered my question in the RubyConf Slack with this: "FWIW, the Pickaxe book style is Class.method for class methods, and Class#method for instance methods. Using :: for class methods is an older style" – Keith Bennett Dec 11 '22 at 08:34

1 Answers1

1

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.

Lorenzo Zabot
  • 147
  • 7
  • This answer does not address my question, which was not about how to call the method, but how to document it. That the notation in documentation has no meaning in actual code is irrelevant; I was asking about the best way to document it. And regarding the last link you posted, I already posted a link that illustrated that. – Keith Bennett Dec 03 '22 at 17:10
  • 1
    The [rspec style guide](https://github.com/rubocop/rspec-style-guide#describe-the-methods) suggets to use `.` when writing a describe/context string. – Lorenzo Zabot Dec 04 '22 at 10:54