New signature convention for exceptions

Author: fxn

lib/zeitwerk/cref.rb

@@ -57,14 +57,12 @@ def set(value)
     @mod.const_set(@cname, value)
   end
 
-  # @raise [NameError]
-  #: () -> top
+  #: () -> top ! NameError
   def get
     @mod.const_get(@cname, false)
   end
 
-  # @raise [NameError]
-  #: () -> void
+  #: () -> void ! NameError
   def remove
     @mod.__send__(:remove_const, @cname)
   end

lib/zeitwerk/loader.rb

@@ -229,8 +229,7 @@ def unload
     # This method is not thread-safe, please see how this can be achieved by
     # client code in the README of the project.
     #
-    # @raise [Zeitwerk::Error]
-    #: () -> void
+    #: () -> void ! Zeitwerk::Error
     def reload
       raise ReloadingDisabledError unless reloading_enabled?
       raise SetupRequired unless @setup

lib/zeitwerk/loader/callbacks.rb

@@ -5,8 +5,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
-  # @raise [Zeitwerk::NameError]
-  #: (String) -> void
+  #: (String) -> void ! Zeitwerk::NameError
   internal def on_file_autoloaded(file)
     cref = autoloads.delete(file)
 

lib/zeitwerk/loader/config.rb

@@ -105,8 +105,7 @@ def initialize
   # the same process already manages that directory or one of its ascendants or
   # descendants.
   #
-  # @raise [Zeitwerk::Error]
-  #: (String | Pathname, namespace: Module) -> void
+  #: (String | Pathname, namespace: Module) -> void ! Zeitwerk::Error
   def push_dir(path, namespace: Object)
     unless namespace.is_a?(Module) # Note that Class < Module.
       raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
@@ -171,8 +170,7 @@ def dirs(namespaces: false, ignored: false)
   # You need to call this method before setup in order to be able to reload.
   # There is no way to undo this, either you want to reload or you don't.
   #
-  # @raise [Zeitwerk::Error]
-  #: () -> void
+  #: () -> void ! Zeitwerk::Error
   def enable_reloading
     mutex.synchronize do
       break if @reloading_enabled
@@ -245,9 +243,7 @@ def on_setup(&block)
   #     # ...
   #   end
   #
-  # @raise [TypeError]
-  #: (String) { (top, String) -> void } -> void
-  #| (:ANY) { (String, top, String) -> void } -> void
+  #: (String?) { (top, String) -> void } -> void ! TypeError
   def on_load(cpath = :ANY, &block)
     raise TypeError, "on_load only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
 
@@ -270,9 +266,7 @@ def on_load(cpath = :ANY, &block)
   #     # ...
   #   end
   #
-  # @raise [TypeError]
-  #: (String) { (top, String) -> void } -> void
-  #| (:ANY) { (String, top, String) -> void } -> void
+  #: (String?) { (top, String) -> void } -> void ! TypeError
   def on_unload(cpath = :ANY, &block)
     raise TypeError, "on_unload only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
 

lib/zeitwerk/loader/helpers.rb

@@ -103,8 +103,7 @@ module Zeitwerk::Loader::Helpers
   CNAME_VALIDATOR = Module.new #: Module
   private_constant :CNAME_VALIDATOR
 
-  # @raise [Zeitwerk::NameError]
-  #: (String, String) -> Symbol
+  #: (String, String) -> Symbol ! Zeitwerk::NameError
   private def cname_for(basename, abspath)
     cname = inflector.camelize(basename, abspath)