zeitwerk 1.0.0.alpha → 1.0.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8109591e515376b3aa028f266d2d354be134aa38cc7b062f7130afc1640f91d
-  data.tar.gz: b9c0118d2cbd8aa5dba6bf22be756f3c7ad448c7320958f76e53fc898ad55b76
+  metadata.gz: cb5151594ce18ccd7919a1ed6b7860107ce1bfc1a02a4f9b038d77cc91ce2450
+  data.tar.gz: e403ef92cc0a14b09bcb54d15d53ba821ad3d72e7d6216c3b0e10e6e9c0734f9
 SHA512:
-  metadata.gz: 51bc3e2567f0ef5c6199e56799ab0d851ba7006e35ccf3813d4dde949fe44d9af6848ac4da219e359a017275d86b0fae7fc4657660c8a0c0737ffb02ac78f614
-  data.tar.gz: 4d7051b8d27fc70fd45aaff66c78e00881e758b1d7db1c551026233874f837351aaa72336c1b8fa083b6a83fbc6987f16f0687e9fcf92df8a41f36812d5fad2d
+  metadata.gz: 10f8af59a66e1462c622cfb6f5316c98808113830041f094861b1fa07a2e9a6734d1ea64a01ebc664e9b5dcf20844b443e98c6bbf196fec99a0dcfee76010331
+  data.tar.gz: 226489835ceb91d696138a966b34054755d9fb1e6bb3245cc028d03e156f21df6a949ee329f5575be1501e8bc143afe532037ff95af2a3631e82fe72963e9479

data/README.md

@@ -1,22 +1,45 @@
-# WIP — NOT PUBLISHED — API AND DOCS IN FLUX
-
 # Zeitwerk
 
 [![Build Status](https://travis-ci.com/fxn/zeitwerk.svg?branch=master)](https://travis-ci.com/fxn/zeitwerk)
 
+<!-- TOC -->
+
+- [Zeitwerk](#zeitwerk)
+    - [Introduction](#introduction)
+    - [Synopsis](#synopsis)
+    - [File structure](#file-structure)
+        - [Implicit namespaces](#implicit-namespaces)
+        - [Explicit namespaces](#explicit-namespaces)
+        - [Nested root directories](#nested-root-directories)
+    - [Usage](#usage)
+        - [Setup](#setup)
+        - [Reloading](#reloading)
+        - [Eager loading](#eager-loading)
+        - [Preloading](#preloading)
+        - [Inflection](#inflection)
+            - [Zeitwerk::Inflector](#zeitwerkinflector)
+            - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
+            - [Custom inflector](#custom-inflector)
+        - [Logging](#logging)
+        - [Ignoring parts of the project](#ignoring-parts-of-the-project)
+    - [Supported Ruby versions](#supported-ruby-versions)
+    - [Motivation](#motivation)
+    - [Thanks](#thanks)
+    - [License](#license)
+
+<!-- /TOC -->
+
 ## Introduction
 
 Zeitwerk is an efficient and thread-safe code loader for Ruby.
 
-Given a conventional file structure, Zeitwerk loads the project classes and modules on demand. You don't need to write `require` calls for your own files, rather, you can streamline your programming knowing that your classes and modules are available everywhere.
-
-This feature is efficient, thread-safe, and matches Ruby's semantics for constants.
+Given a conventional file structure, Zeitwerk loads your project's classes and modules on demand. You don't need to write `require` calls for your own files, rather, you can streamline your programming knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and matches Ruby's semantics for constants.
 
 The library is designed so that each gem and application can have their own loader, independent of each other. Each loader has its own configuration, inflector, and optional logger.
 
 Zeitwerk is also able to reload code, which may be handy for web applications. Coordination is needed to reload in a thread-safe manner. The documentation below explains how to do this.
 
-Finally, in some production setups it may be interesting to be able to eager load all code upfront. Zeitwerk is able to do that too.
+Finally, in some production setups it may be optimal to eager load all code upfront. Zeitwerk is able to do that too.
 
 ## Synopsis
 
@@ -26,7 +49,7 @@ Main interface for gems:
 # lib/my_gem.rb (main file)
 
 require "zeitwerk"
-Zeitwerk::Loader.for_gem.setup
+Zeitwerk::Loader.for_gem.setup # ready!
 
 module MyGem
   # ...
@@ -38,10 +61,10 @@ Main generic interface:
 ```ruby
 loader = Zeitwerk::Loader.new
 loader.push_dir(...)
-loader.setup
+loader.setup # ready!
 ```
 
-Zeitwerk is ready to right after the `setup` call.
+The `loader` variable can go out of scope. Zeitwerk keeps a registry with all of them, and so the object won't be garbage collected and remain active.
 
 Later, you can reload if you want to:
 
@@ -49,21 +72,21 @@ Later, you can reload if you want to:
 loader.reload
 ```
 
-and you can also eager load:
+and you can also eager load all the code:
 
 ```ruby
 loader.eager_load
 ```
 
-Broadcast `eager_load` to all loaders:
+It is also possible to broadcast `eager_load` to all instances:
 
 ```
 Zeitwerk::Loader.eager_load_all
 ```
 
-## Compatible file structure
+## File structure
 
-To have a file structure compatible with Zeitwerk, just name files and directories after the name of the classes and modules they define:
+To have a file structure Zeitwerk can work with, just name files and directories after the name of the classes and modules they define:
 
 ```
 lib/my_gem.rb         -> MyGem
@@ -79,7 +102,7 @@ loader.push_dir(Rails.root.join("app/models"))
 loader.push_dir(Rails.root.join("app/controllers"))
 ```
 
-you get the mappings
+Zeitwerk understands that their respective files and subdirectories belong to the root namespace:
 
 ```
 app/models/user.rb                        -> User
@@ -98,85 +121,144 @@ app/controllers/admin/users_controller.rb -> Admin::UsersController
 
 ### Explicit namespaces
 
-Classes and modules that act as namespaces can also be explictly defined, though. For instance, consider
+Classes and modules that act as namespaces can also be explicitly defined, though. For instance, consider
 
 ```
-app/models/hotel.rb      -> Hotel
-app/models/hotel/pricing -> Hotel::Pricing
+app/models/hotel.rb         -> Hotel
+app/models/hotel/pricing.rb -> Hotel::Pricing
 ```
 
-Zeitwerk does not autovivify a `Hotel` module in that case. The file `app/models/hotel.rb` explictly defines `Hotel` and Zeitwerk loads it as needed before going for `Hotel::Pricing`.
+Zeitwerk does not autovivify a `Hotel` module in that case. The file `app/models/hotel.rb` explicitly defines `Hotel` and Zeitwerk loads it as needed before going for `Hotel::Pricing`.
 
-## Synopsis
+### Nested root directories
 
+Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
 
+Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
 
-The autoloading semantics provided by Zeitwerk match Ruby's. Zeitwerk bases autoloading on `Kernel#autoload`, which has builtin support in the interpreter in constant lookup algorithms and related APIs.
+```
+app/models/concerns/geolocatable.rb
+```
 
-Autoloadable files can be required. The idea is to _not_ use `require` at all with a gem managed by Zeitwerk, but support for this exists in case your users have `require` calls already in place and upgrade, for example.
+should define `Geolocatable`, not `Concerns::Geolocatable`.
 
-## Use case: Gems
+## Usage
 
-To use Zeitwerk in a gem just throw these couple of lines in the main file:
+### Setup
+
+Loaders are ready to load code right after calling `setup` on them:
 
 ```ruby
-# lib/my_gem.rb
+loader.setup
+```
 
-require "zeitwerk"
-Zeitwerk::Loader.for_gem.setup
+Customization should generally be done before that call. In particular, in the generic interface you may set the root directories from which you want to load files:
 
-module MyGem
-  # ...
-end
+```ruby
+loader.push_dir(...)
+loader.push_dir(...)
+loader.setup
 ```
 
-The loader of your gem is exclusive, it has its own configuration, inflector, and logger.
+The loader returned by `Zeitwerk::Loader.for_gem` has the directory of the caller pushed, normally that is the absolute path of `lib`. In that sense, `for_gem` can be used also by projects with a gem structure, even if they are not technically gems. That is, you don't need a gemspec or anything.
 
-## Use case: Generic interface
+### Reloading
 
-The generic interface to use Zeitwerk in a different context is
+In order to reload code:
 
 ```ruby
-require "zeitwerk"
+loader.reload
+```
 
-loader = Zeitwerk::Loader.new
-loader.push_dir("...")
+Generally speaking, reloading is useful for services, servers, web applications, etc. Gems that implement regular libraries, so to speak, won't normally have a use case for reloading.
+
+It is important to highlight that this is and instance method. Therefore, reloading the code of a project managed by a particular loader does _not_ reload the code of other gems using Zeitwerk at all.
+
+In order for reloading to be thread-safe, you need to implement some coordination. For example, a web framework that serves each request with its own thread may have a globally accessible RW lock. When a request comes in, the framework acquires the lock for reading at the beginning, and the code in the framework that calls `loader.reload` needs to acquire the lock for writing.
+
+### Eager loading
+
+Zeitwerk instances are able to eager load their managed files:
+
+```ruby
+loader.eager_load
+```
+
+You can opt-out of eager loading individual files or directories:
+
+```ruby
+db_adapters = File.expand_path("my_gem/db_adapters", __dir__)
+cache_adapters = File.expand_path("my_gem/cache_adapters", __dir__)
+loader.do_not_eager_load(db_adapters, cache_adapters)
 loader.setup
+loader.eager_load # won't go into the directories with db/cache adapters
 ```
 
-A loader instantiated that way is independent of other loaders. It has its own configuration, inflector, and logger.
+Files and directories excluded from eager loading can still be loaded on demand, so an idiom like this is possible:
 
-The variable used to setup the loader can get out of scope. The instance won't be garbage collected because Zeitwerk keeps a registry of them.
+```ruby
+db_adapter = Object.const_get("MyGem::DbAdapters::#{config[:db_adapter]}")
+```
+
+Please check `Zeitwerk::Loader#ignore` if you want files or directories to not be even autoloadable.
+
+If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all instances:
+
+```ruby
+Zeitwerk::Loader.eager_load_all
+```
+
+In that case, exclusions are per autoloader, and so will apply to each of them accordingly.
+
+This may be handy in top-level services, like web applications.
+
+### Preloading
+
+Zeitwerk instances are able to preload files and directories.
+
+```ruby
+loader.preload("app/models/videogame.rb")
+loader.preload("app/models/book.rb")
+```
+
+The example above depicts several calls are supported, but `preload` accepts multiple arguments and arrays of strings as well.
+
+The call can happen after `setup` (preloads on the spot), or before `setup` (executes during setup).
+
+If you're using reloading, preloads run on each reload too.
 
-## Inflection
+This is a feature specifically thought for STIs in Rails, preloading the leafs of a STI tree ensures all classes are known when doing a query.
+
+### Inflection
 
 Each individual loader needs an inflector to figure out which constant path would a given file or directory map to. Zeitwerk ships with two basic inflectors.
 
-### Zeitwerk::Inflector
+#### Zeitwerk::Inflector
 
-This is a super basic inflector that converts snake case to camel case preserving upper case letters:
+This is a very basic inflector that converts snake case to camel case:
 
 ```
 user             -> User
 users_controller -> UsersController
 html_parser      -> HtmlParser
-HTML_parser      -> HTMLParser
 ```
 
+There are no inflection rules or global configuration that can affect this inflector. It is deterministic.
+
 This is the default inflector.
 
-### Zeitwerk::GemInflector
+#### Zeitwerk::GemInflector
 
 The loader instantiated behind the scenes by `Zeitwerk::Loader.for_gem` gets assigned by default an inflector that is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
 
-### Custom inflector
+#### Custom inflector
 
 The inflectors that ship with Zeitwerk are deterministic and simple. But you can configure your own:
 
 ```ruby
 # frozen_string_literal: true
 
-class MyInflector < Zeitwerk::Inflector
+class MyInflector < Zeitwerk::Inflector # or Zeitwerk::GemInflector
   def camelize(basename, _abspath)
     case basename
     when "api"
@@ -197,113 +279,44 @@ The second argument, `abspath`, is a string with the absolute path to the file o
 Then, assign the inflector before calling `setup`:
 
 ```
-loader = Zeitwerk::Loader.new
 loader.inflector = MyInflector.new
-loader.setup
 ```
 
-## Logging
+This needs to be assigned before the call to `setup`.
 
-Zeitwerk is silent by default, but you can configure a callable as logger.
+### Logging
 
-In the case of gems, for example:
+Zeitwerk is silent by default, but you can configure a callable as logger:
 
 ```ruby
-require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
 loader.logger = method(:puts)
-loader.setup
 ```
 
-If there is a logger configured, the the loader is going to print traces when autoloads are set, files preloaded, files autoloaded, and modules autovivified from directories.
+If there is a logger configured, the loader is going to print traces when autoloads are set, files loaded, and modules autovivified.
 
-If your project has namespaces, you'll notice in the traces Zeitwerk sets autoloads for _directories_. That's a technique used to be able to be lazy and avoid unnecessary tree walks. It sets autoloads one depth level at a time, and only on demand.
+If your project has namespaces, you'll notice in the traces Zeitwerk sets autoloads for _directories_. That's a technique used to be able to descend into subdirectories on demand, avoiding that way unnecessary tree walks.
 
-## Reloading
+### Ignoring parts of the project
 
-In order to reload code, unload and setup:
+Sometimes it might be convenient to tell Zeitwerk to completely ignore some particular file or directory. For example, let's suppose that your gem decorates something in `Kernel`:
 
 ```ruby
-loader.unload
-loader.setup
-```
-
-It is important to highlight that these are instance methods. Therefore, reloading the project managed by your autoloader does _not_ reload the code of other gems using Zeitwerk.
+# lib/my_gem/core_ext/kernel.rb
 
-Generally speaking, reloading is useful for services, servers, web applications, etc. Gems that implement regular libraries, so to speak, won't normally have a use case for reloading.
-
-## Eager loading
-
-Zeitwerk instances are able to eager load their managed files:
-
-```ruby
-loader.eager_load
-```
-
-You can opt-out of eager loading individual files or directories:
-
-```ruby
-require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
-
-db_adapters = File.expand_path("my_gem/db_adapters", __dir__)
-cache_adapters = File.expand_path("my_gem/cache_adapters", __dir__)
-loader.do_not_eager_load(db_adapters, cache_adapters)
-loader.eager_load # won't go into the directories with db/cache adapters
-```
-
-Files and directories excluded from eager loading can still be autoloaded, so a technique like this is possible:
-
-```ruby
-db_adapter = Object.const_get("MyGem::DbAdapters::#{config[:db_adapter]}")
+Kernel.module_eval do
+  # ...
+end
 ```
 
-You can even opt-out from eager loading entirely:
+That file does not follow the conventions and you need to tell Zeitwerk:
 
 ```ruby
-require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
-loader.do_not_eager_load(__dir__)
+kernel_ext = File.expand_path("my_gem/core_ext/kernel.rb", __dir__)
+loader.ignore(kernel_ext)
 loader.setup
 ```
 
-If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all registered instances:
-
-```ruby
-Zeitwerk::Loader.eager_load_all
-```
-
-In that case, exclusions are per autoloader, and so will apply to each of them accordingly.
-
-This may be handy in top-level services, like web applications.
-
-## Preloading
-
-Zeitwerk instances are able to preload files and directories.
-
-```ruby
-loader.preload("app/models/videogame.rb")
-loader.preload("app/models/book.rb")
-```
-
-The example above depicts several calls are supported, but `preload` accepts multiple arguments and arrays of strings as well.
-
-The call can happen after `setup` (preloads on the spot), or before `setup` (executes during setup).
-
-If you're using reloading, preloads run on each reload too.
-
-This is a feature specifically thought for STIs in Rails, preloading the leafs of an STI tree ensures all classes are known when doing a query.
-
-Instead of preloading, gems can issue regular requires in the main file:
-
-```ruby
-require "zeitwerk"
-Zeitwerk::Loader.for_gem.setup
-
-module MyGem
-  require "preload_me"
-end
-```
+You can pass several arguments to this method, also an array of strings. And you can call `ignore` multiple times too.
 
 ## Supported Ruby versions
 

data/lib/zeitwerk/gem_inflector.rb

@@ -2,17 +2,18 @@
 
 module Zeitwerk
   class GemInflector < Inflector
-    # @param gem_entry_point [String]
+    # @param root_file [String]
     def initialize(root_file)
-      namespace = File.basename(root_file, ".rb")
-      @version_file = File.join(namespace, "version.rb")
+      namespace     = File.basename(root_file, ".rb")
+      lib_dir       = File.dirname(root_file)
+      @version_file = File.join(lib_dir, namespace, "version.rb")
     end
 
     # @param basename [String]
     # @param abspath [String]
     # @return [String]
     def camelize(basename, abspath)
-      basename == "version" && abspath.end_with?(@version_file) ? "VERSION" : super
+      (basename == "version" && abspath == @version_file) ? "VERSION" : super
     end
   end
 end

data/lib/zeitwerk/inflector.rb

@@ -2,19 +2,17 @@
 
 module Zeitwerk
   class Inflector # :nodoc:
-    # Given a basename without extension, returns the name of the constant
-    # expected to be defined in such file or directory.
+    # Very basic snake case -> camel case conversion.
     #
     #   Zeitwerk::Inflector.camelize("post", ...)             # => "Post"
     #   Zeitwerk::Inflector.camelize("users_controller", ...) # => "UsersController"
     #   Zeitwerk::Inflector.camelize("api", ...)              # => "Api"
-    #   Zeitwerk::Inflector.camelize("HTML", ...)             # => "HTML"
     #
     # @param basename [String]
     # @param _abspath [String]
     # @return [String]
     def camelize(basename, _abspath)
-      basename.gsub(/(?:\A|_)(\w)/) { $1.capitalize }
+      basename.split('_').map(&:capitalize).join
     end
   end
 end

data/lib/zeitwerk/loader.rb

@@ -4,20 +4,10 @@ require "set"
 
 module Zeitwerk
   class Loader
-    # Object used to infer the constant name from a basename without extension.
-    # Default is an instance of Zeitwerk::Inflector.
-    #
-    #   inflector.camelize("users_controller", realname) # => "UsersController"
-    #
-    # For context, it receives also the absolute path to the file or directory
-    # name.
-    #
     # @return [#camelize]
     attr_accessor :inflector
 
-    # An optional callable to log when a constant is loaded, `nil` by default.
-    #
-    # @return [nil, #call]
+    # @return [#call, nil]
     attr_accessor :logger
 
     # Absolute paths of directories from which you want to load constants. This
@@ -26,11 +16,9 @@ module Zeitwerk
     # Stored in a hash to preserve order, easily handle duplicates, and also be
     # able to have a fast lookup, needed for detecting nested paths.
     #
-    #   {
-    #     "/Users/fxn/blog/app/assets"   => true,
-    #     "/Users/fxn/blog/app/channels" => true,
-    #     ...
-    #   }
+    #   "/Users/fxn/blog/app/assets"   => true,
+    #   "/Users/fxn/blog/app/channels" => true,
+    #   ...
     #
     # @private
     # @return [{String => true}]
@@ -51,8 +39,9 @@ module Zeitwerk
     # Maps real absolute paths for which an autoload has been set to their
     # corresponding parent class or module and constant name.
     #
-    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, "User"]
+    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, "User"],
     #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, "Pricing"]
+    #   ...
     #
     # @private
     # @return [{String => (Module, String)}]
@@ -84,6 +73,10 @@ module Zeitwerk
     # @return [Mutex]
     attr_reader :mutex
 
+    # This tracer listens to `:class` events, and it is used to support explicit
+    # namespaces. Benchmarks have shown the tracer does not impact performance
+    # in any measurable way.
+    #
     # @private
     # @return [TracePoint]
     attr_reader :tracer
@@ -92,17 +85,16 @@ module Zeitwerk
       self.inflector = Inflector.new
 
       @dirs                  = {}
-      @autoloads             = {}
       @preloads              = []
-      @lazy_subdirs          = {}
       @ignored               = Set.new
+      @autoloads             = {}
+      @lazy_subdirs          = {}
       @eager_load_exclusions = Set.new
-      @mutex                 = Mutex.new
-      @setup                 = false
-      @eager_loaded          = false
 
-      # We have run several benchmarks that have shown having a trace point for
-      # the :class event does not impact performance in any measurable way.
+      @mutex        = Mutex.new
+      @setup        = false
+      @eager_loaded = false
+
       @tracer = TracePoint.trace(:class) do |tp|
         unless lazy_subdirs.empty? # do not even compute the hash key if not needed
           if subdirs = lazy_subdirs.delete(tp.self.name)
@@ -148,7 +140,7 @@ module Zeitwerk
       end
     end
 
-    # Files or directories to be totally ignored by Zeitwerk.
+    # Files or directories to be totally ignored.
     #
     # @param paths [<String, Pathname, <String, Pathname>>]
     # @return [void]
@@ -156,11 +148,7 @@ module Zeitwerk
       mutex.synchronize { ignored.merge(expand_paths(paths)) }
     end
 
-    # Sets autoloads in the root namespace and preloads files if any.
-    #
-    # Once started, this instance is ready to trace loaded constants if logging
-    # is enabled, to autovivify modules on demand, and to descend further
-    # directory levels to lazily set more autoloads.
+    # Sets autoloads in the root namespace and preloads files, if any.
     #
     # @return [void]
     def setup
@@ -181,6 +169,7 @@ module Zeitwerk
     # else, they are eligible for garbage collection, which would effectively
     # unload them.
     #
+    # @private
     # @return [void]
     def unload
       mutex.synchronize do
@@ -204,7 +193,11 @@ module Zeitwerk
       end
     end
 
-    # Docs pending.
+    # Unloads all loaded code, and calls setup again so that the loader is able
+    # to pick any changes in the file system.
+    #
+    # This method is not thread-safe, please see how this can be achieved by
+    # client code in the README of the project.
     #
     # @return [void]
     def reload
@@ -212,8 +205,10 @@ module Zeitwerk
       setup
     end
 
-    # Eager loads in the root directories, recursively. Files do not need to be
-    # in `$LOAD_PATH`, absolute file names are used.
+    # Eager loads all files in the root directories, recursively. Files do not
+    # need to be in `$LOAD_PATH`, absolute file names are used. Ignored files
+    # are not eager loaded. You can opt-out specifically in specific files and
+    # directories with `do_not_eager_load`.
     #
     # @return [void]
     def eager_load
@@ -228,7 +223,8 @@ module Zeitwerk
       end
     end
 
-    # Let eager load ignore the given files or directories.
+    # Let eager load ignore the given files or directories. The constants
+    # defined in those files are still autoloadable.
     #
     # @param paths [<String, Pathname, <String, Pathname>>]
     # @return [void]
@@ -236,7 +232,7 @@ module Zeitwerk
       mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
     end
 
-    # --- Class methods -----------------------------------------------------------------------------
+    # --- Class methods ---------------------------------------------------------------------------
 
     # This is a shortcut for
     #
@@ -257,14 +253,14 @@ module Zeitwerk
       Registry.loader_for_gem(called_from)
     end
 
-    # Broadcasts `eager_load` to all instances.
+    # Broadcasts `eager_load` to all loaders.
     #
     # @return [void]
     def self.eager_load_all
       Registry.loaders.each(&:eager_load)
     end
 
-    # --- Calbacks ----------------------------------------------------------------------------------
+    # --- Callbacks -------------------------------------------------------------------------------
 
     # Callback invoked from Kernel when a managed file is loaded.
     #
@@ -293,9 +289,8 @@ module Zeitwerk
       end
     end
 
-    private # ---------------------------------------------------------------------------------------
+    private # -------------------------------------------------------------------------------------
 
-    # @private
     # @return [<String>]
     def actual_dirs
       dirs.each_key.reject { |dir| ignored.member?(dir) }
@@ -303,6 +298,7 @@ module Zeitwerk
 
     # @param dir [String]
     # @param parent [Module]
+    # @return [void]
     def set_autoloads_in_dir(dir, parent)
       each_abspath(dir) do |abspath|
         cname = inflector.camelize(File.basename(abspath, ".rb"), abspath)
@@ -320,16 +316,16 @@ module Zeitwerk
       end
     end
 
-    # @param subdir [String]
     # @param parent [Module]
     # @paran cname [String]
+    # @param subdir [String]
     # @return [void]
     def autoload_subdir(parent, cname, subdir)
       if autoload_for?(parent, cname)
-        # If there is already an autoload for this cname, maybe there are multiple
-        # directories defining the namespace, or the cname is going to be defined
-        # in a file (not autovivified). In either case, we do not need to issue
-        # another autoload, the existing one is fine.
+        # If there is already an autoload for this cname, maybe there are
+        # multiple directories defining the namespace, or the cname is going to
+        # be defined in a file (explicit namespace). In either case, we do not
+        # need to issue another autoload, the existing one is fine.
         (lazy_subdirs[cpath(parent, cname)] ||= []) << subdir
       elsif !parent.const_defined?(cname, false)
         # First time we find this namespace, set an autoload for it.
@@ -342,9 +338,9 @@ module Zeitwerk
       end
     end
 
-    # @param file [String]
     # @param parent [Module]
     # @paran cname [String]
+    # @param file [String]
     # @return [void]
     def autoload_file(parent, cname, file)
       if autoload_path = autoload_for?(parent, cname)
@@ -390,12 +386,13 @@ module Zeitwerk
 
     # @param parent [Module]
     # @param cname [String]
-    # @return [nil, String]
+    # @return [String, nil]
     def autoload_for?(parent, cname)
       parent.autoload?(cname) || Registry.inception?(cpath(parent, cname))
     end
 
     # @param dir [String]
+    # @return [void]
     def eager_load_dir(dir)
       each_abspath(dir) do |abspath|
         next if eager_load_exclusions.member?(abspath)
@@ -445,7 +442,7 @@ module Zeitwerk
     # @param cname [String]
     # @return [String]
     def cpath(parent, cname)
-      parent.equal?(Object) ? cname : "#{parent}::#{cname}"
+      parent.equal?(Object) ? cname : "#{parent.name}::#{cname}"
     end
 
     # @param dir [String]

data/lib/zeitwerk/registry.rb

@@ -19,17 +19,14 @@ module Zeitwerk
 
       # Maps real paths to the loaders responsible for them.
       #
-      # This information is used by our decorated Kernel#require to be able to
-      # invoke callbacks.
+      # This information is used by our decorated `Kernel#require` to be able to
+      # invoke callbacks and autovivify modules.
       #
       # @private
       # @return [{String => Zeitwerk::Loader}]
       attr_reader :autoloads
 
-      # This hash table addresses an edge case in which an autoload is ignored:
-      #
-      #   Object.autoload(:MyGem, path)
-      #   Object.autoload?(:MyGem) # => nil (!!!!)
+      # This hash table addresses an edge case in which an autoload is ignored.
       #
       # For example, let's suppose we want to autoload in a gem like this:
       #
@@ -41,16 +38,19 @@ module Zeitwerk
       #   module MyGem
       #   end
       #
-      # if you require "my_gem", this happens while setting up autoloads:
+      # if you require "my_gem", as Bundler would do, this happens while setting
+      # up autoloads:
       #
-      #   1. Object.autoload?(:MyGem) returns `nil`.
+      #   1. Object.autoload?(:MyGem) returns `nil` because the autoload for
+      #      the constant is issued by Zeitwerk while the same file is being
+      #      required.
       #   2. The constant `MyGem` is undefined while setup runs.
       #
       # Therefore, a directory `lib/my_gem` would autovivify a module according to
       # the existing information. But that would be wrong.
       #
       # To overcome this fundamental limitation, we keep track of the constant
-      # paths that are in this situation ---in the example above "MyGem"---, and
+      # paths that are in this situation ---in the example above, "MyGem"--- and
       # take this collection into account for the autovivification logic.
       #
       # Note that you cannot generally address this by moving the setup code
@@ -61,16 +61,6 @@ module Zeitwerk
       #     include MyConcern
       #   end
       #
-      # and it would be inelegant to ask users to split that into
-      #
-      #   # NO WAY WE ARE GOING TO ASK PEOPLE TO DO THIS.
-      #   module MyGem
-      #   end
-      #   loader.setup
-      #   module MyGem
-      #     include MyConcern
-      #   end
-      #
       # @private
       # @return [{String => (String, Zeitwerk::Loader)}]
       attr_reader :inceptions
@@ -79,12 +69,13 @@ module Zeitwerk
       #
       # @private
       # @param loader [Zeitwerk::Loader]
+      # @return [void]
       def register_loader(loader)
         loaders << loader
       end
 
-      # This method returns always a loader, and it returns the same instance
-      # for the same root file. That is how Zeitwerk.start is idempotent.
+      # This method returns always a loader, the same instance for the same root
+      # file. That is how Zeitwerk::Loader.for_gem is idempotent.
       #
       # @private
       # @param root_file [String]
@@ -101,12 +92,14 @@ module Zeitwerk
       # @private
       # @param loader [Zeitwerk::Loader]
       # @param realpath [String]
+      # @return [void]
       def register_autoload(loader, realpath)
         autoloads[realpath] = loader
       end
 
       # @private
       # @param realpath [String]
+      # @return [void]
       def unregister_autoload(realpath)
         autoloads.delete(realpath)
       end
@@ -115,6 +108,7 @@ module Zeitwerk
       # @param cpath [String]
       # @param realpath [String]
       # @param loader [Zeitwerk::Loader]
+      # @return [void]
       def register_inception(cpath, realpath, loader)
         inceptions[cpath] = [realpath, loader]
       end
@@ -137,6 +131,7 @@ module Zeitwerk
 
       # @private
       # @param loader [Zeitwerk::Loader]
+      # @return [void]
       def on_unload(loader)
         autoloads.delete_if { |_path, object| object == loader }
         inceptions.delete_if { |_cpath, (_path, object)| object == loader }

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "1.0.0.alpha"
+  VERSION = "1.0.0.beta"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha
+  version: 1.0.0.beta
 platform: ruby
 authors:
 - Xavier Noria