Use #: for RBS annotations

I have annotated signatures since the first version of Zeitwerk. For me, they
are an essential aid to understand and use the code, both public and private.

In the case of Zeitwerk, the API is described in English in the README. These
signatures are mostly internal documentation for readers of the code.

You need to know what a method accepts, returns, yields, and what may raise. And
that is the case regardless of the dynamic or static nature of your type system.

At the beginning I used my own notation, then adopted RBS, and now a consensus
towards using #: as a marker seems to be taking shape.

This pull request to Sorbet

    sorbet/sorbet#8470

inspired me to join this trend.

Author: fxn

lib/zeitwerk.rb

@@ -19,7 +19,7 @@ module Zeitwerk
   # This is a dangerous method.
   #
   # @experimental
-  # @sig () -> void
+  #: () -> void
   def self.with_loader
     loader = Zeitwerk::Loader.new
     yield loader

lib/zeitwerk/core_ext/kernel.rb

@@ -19,7 +19,7 @@ class << self
     alias_method :zeitwerk_original_require, :require
   end
 
-  # @sig (String) -> true | false
+  #: (String) -> bool
   def require(path)
     if loader = Zeitwerk::Registry.autoloads.registered?(path)
       if path.end_with?(".rb")

lib/zeitwerk/core_ext/module.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk::ConstAdded # :nodoc:
-  # @sig (Symbol) -> void
+  #: (Symbol) -> void
   def const_added(cname)
     if loader = Zeitwerk::Registry.explicit_namespaces.loader_for(self, cname)
       namespace = const_get(cname, false)

lib/zeitwerk/cref.rb

@@ -2,69 +2,69 @@
 
 # This private class encapsulates pairs (mod, cname).
 #
-# Objects represent the constant cname in the class or module object mod, and
-# have API to manage them. Examples:
+# Objects represent the constant `cname` in the class or module object `mod`,
+# and have API to manage them. Examples:
 #
 #   cref.path
 #   cref.set(value)
 #   cref.get
 #
-# The constant may or may not exist in mod.
+# The constant may or may not exist in `mod`.
 class Zeitwerk::Cref
   require_relative "cref/map"
 
   include Zeitwerk::RealModName
 
-  # @sig Module
+  #: Module
   attr_reader :mod
 
-  # @sig Symbol
+  #: Symbol
   attr_reader :cname
 
   # The type of the first argument is Module because Class < Module, class
   # objects are also valid.
   #
-  # @sig (Module, Symbol) -> void
+  #: (Module, Symbol) -> void
   def initialize(mod, cname)
     @mod   = mod
     @cname = cname
     @path  = nil
   end
 
-  # @sig () -> String
+  #: () -> String
   def path
     @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
   end
   alias to_s path
 
-  # @sig () -> String?
+  #: () -> String?
   def autoload?
     @mod.autoload?(@cname, false)
   end
 
-  # @sig (String) -> bool
+  #: (String) -> nil
   def autoload(abspath)
     @mod.autoload(@cname, abspath)
   end
 
-  # @sig () -> bool
+  #: () -> bool
   def defined?
     @mod.const_defined?(@cname, false)
   end
 
-  # @sig (top) -> top
+  #: (top) -> top
   def set(value)
     @mod.const_set(@cname, value)
   end
 
   # @raise [NameError]
-  # @sig () -> top
+  #: () -> top
   def get
     @mod.const_get(@cname, false)
   end
 
   # @raise [NameError]
-  # @sig () -> void
+  #: () -> void
   def remove
     @mod.__send__(:remove_const, @cname)
   end

lib/zeitwerk/cref/map.rb

@@ -69,44 +69,45 @@
 # unnecessary cref objects for constants we do not manage (but we do not know in
 # advance there).
 class Zeitwerk::Cref::Map # :nodoc: all
+  #: () -> void
   def initialize
     @map = {}
     @map.compare_by_identity
     @mutex = Mutex.new
   end
 
-  # @sig (Zeitwerk::Cref, V) -> V
+  #: (Zeitwerk::Cref, top) -> top
   def []=(cref, value)
     @mutex.synchronize do
       cnames = (@map[cref.mod] ||= {})
       cnames[cref.cname] = value
     end
   end
 
-  # @sig (Zeitwerk::Cref) -> top?
+  #: (Zeitwerk::Cref) -> top
   def [](cref)
     @mutex.synchronize do
       @map[cref.mod]&.[](cref.cname)
     end
   end
 
-  # @sig (Zeitwerk::Cref, { () -> V }) -> V
+  #: (Zeitwerk::Cref, { () -> top }) -> top
   def get_or_set(cref, &block)
     @mutex.synchronize do
       cnames = (@map[cref.mod] ||= {})
       cnames.fetch(cref.cname) { cnames[cref.cname] = block.call }
     end
   end
 
-  # @sig (Zeitwerk::Cref) -> top?
+  #: (Zeitwerk::Cref) -> top
   def delete(cref)
     delete_mod_cname(cref.mod, cref.cname)
   end
 
   # Ad-hoc for loader_for, called from const_added. That is a hot path, I prefer
   # to not create a cref in every call, since that is global.
   #
-  # @sig (Module, Symbol) -> top?
+  #: (Module, Symbol) -> top
   def delete_mod_cname(mod, cname)
     @mutex.synchronize do
       if cnames = @map[mod]
@@ -117,7 +118,7 @@ def delete_mod_cname(mod, cname)
     end
   end
 
-  # @sig (top) -> void
+  #: (top) -> void
   def delete_by_value(value)
     @mutex.synchronize do
       @map.delete_if do |mod, cnames|
@@ -129,7 +130,7 @@ def delete_by_value(value)
 
   # Order of yielded crefs is undefined.
   #
-  # @sig () { (Zeitwerk::Cref) -> void } -> void
+  #: () { (Zeitwerk::Cref) -> void } -> void
   def each_key
     @mutex.synchronize do
       @map.each do |mod, cnames|
@@ -140,14 +141,14 @@ def each_key
     end
   end
 
-  # @sig () -> void
+  #: () -> void
   def clear
     @mutex.synchronize do
       @map.clear
     end
   end
 
-  # @sig () -> bool
+  #: () -> bool
   def empty? # for tests
     @mutex.synchronize do
       @map.empty?

lib/zeitwerk/error.rb

@@ -5,6 +5,7 @@ class Error < StandardError
   end
 
   class ReloadingDisabledError < Error
+    #: () -> void
     def initialize
       super("can't reload, please call loader.enable_reloading before setup")
     end
@@ -14,6 +15,7 @@ class NameError < ::NameError
   end
 
   class SetupRequired < Error
+    #: () -> void
     def initialize
       super("please, finish your configuration and call Zeitwerk::Loader#setup once all is ready")
     end

lib/zeitwerk/gem_inflector.rb

@@ -2,14 +2,14 @@
 
 module Zeitwerk
   class GemInflector < Inflector
-    # @sig (String) -> void
+    #: (String) -> void
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
       root_dir      = File.dirname(root_file)
       @version_file = File.join(root_dir, namespace, "version.rb")
     end
 
-    # @sig (String, String) -> String
+    #: (String, String) -> String
     def camelize(basename, abspath)
       abspath == @version_file ? "VERSION" : super
     end

lib/zeitwerk/gem_loader.rb

@@ -10,12 +10,12 @@ class GemLoader < Loader
     private_class_method :new
 
     # @private
-    # @sig (String, bool) -> Zeitwerk::GemLoader
+    #: (String, namespace: Module, warn_on_extra_files: boolish) -> Zeitwerk::GemLoader
     def self.__new(root_file, namespace:, warn_on_extra_files:)
       new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
     end
 
-    # @sig (String, bool) -> void
+    #: (String, namespace: Module, warn_on_extra_files: boolish) -> void
     def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
@@ -30,15 +30,15 @@ def initialize(root_file, namespace:, warn_on_extra_files:)
       push_dir(@root_dir, namespace: namespace)
     end
 
-    # @sig () -> void
+    #: () -> void
     def setup
       warn_on_extra_files if @warn_on_extra_files
       super
     end
 
     private
 
-    # @sig () -> void
+    #: () -> void
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 

lib/zeitwerk/inflector.rb

@@ -11,7 +11,7 @@ class Inflector
     #
     # Takes into account hard-coded mappings configured with `inflect`.
     #
-    # @sig (String, String) -> String
+    #: (String, String) -> String
     def camelize(basename, _abspath)
       overrides[basename] || basename.split('_').each(&:capitalize!).join
     end
@@ -28,7 +28,7 @@ def camelize(basename, _abspath)
     #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
     #   inflector.camelize("users_controller", abspath) # => "UsersController"
     #
-    # @sig (Hash[String, String]) -> void
+    #: (Hash[String, String]) -> void
     def inflect(inflections)
       overrides.merge!(inflections)
     end
@@ -38,7 +38,7 @@ def inflect(inflections)
     # Hard-coded basename to constant name user maps that override the default
     # inflection logic.
     #
-    # @sig () -> Hash[String, String]
+    #: () -> Hash[String, String]
     def overrides
       @overrides ||= {}
     end

lib/zeitwerk/internal.rb

@@ -2,7 +2,7 @@
 
 # This is a private module.
 module Zeitwerk::Internal
-  # @sig (Symbol) -> void
+  #: (Symbol) -> void
   def internal(method_name)
     private method_name