RubyGems 3.3.10 restores documentation hidden by source layout

A documentation comment can be present in a source file and still be absent from the generated reference. RubyGems 3.3.10 fixes two cases where RDoc's interpretation of source layout prevented useful documentation from appearing. Neither required rewriting the API's explanation. Both required placing the existing documentation controls where the generator associated them with the intended code.

The March 23 release announcement lists those documentation repairs alongside installation of Bundler 2.3.10 as a default gem. This is a small maintenance update, but the fixes expose a dependency that source review can overlook. Generated reference material depends on how comments and declarations relate, not simply on whether explanatory prose exists somewhere in the file.

I find Ruby code approachable in part because its declarations and ordinary control flow are readable. Reference documentation remains necessary when the operation belongs to package tooling with behaviour a caller should not infer from a method name. An example hidden by the generator is unavailable to exactly the reader who needs that explanation.

A directive affected the whole module

Pull request 5396 moves a :stopdoc: directive in the compatibility source. Its commit explanation says that placing the directive at the top level stops documentation for the entire module, rather than only the relevant portion in that file.

The patch removes the directive from the beginning of the file and places it inside the Gem module declaration. This changes the scope at which RDoc encounters the instruction. Compatibility material can remain outside the generated reference without suppressing the top-level module's documentation as a whole.

The distinction is consequential in Ruby, where a module's implementation can appear across source files. A documentation instruction near one part of that implementation can influence the reference for the shared module. The intended unit of omission therefore needs to match the documentation generator's scope rules.

This is not a change to the runtime meaning of the compatibility constants. The patch changes how the reference generator sees the source. A runtime-oriented check would not by itself demonstrate that the top-level documentation had become visible. The defect concerns the generated representation that readers consume.

The example needed to precede its class

Pull request 5399 repairs the Gem::Package example. Its explanation is direct about the cause. Other code must not sit between the documentation and the class definition. In the earlier layout, several require_relative calls separated the explanatory block from class Gem::Package.

The patch moves those requirements above the example and leaves the comment block next to the class declaration. It also adjusts the comment marker introducing the example. The result is that RDoc can associate the existing explanation with the class it documents.

The relative ordering is the substance of the fix. Dependency-loading statements still exist, and the class still follows them in executable source. RDoc now encounters the documentation block in the position where it expects class documentation. Source text and generated reference become consistent without inventing another copy of the example elsewhere. There is consequently one explanation to maintain beside the implementation.

The example's opening explains that Gem::Package builds a .gem from a Gem::Specification. Its comments also distinguish files in the archive from Ruby files in the gem, and mention verification performed by extraction and contents operations. Those are useful details for someone working with package contents, so making the example visible improves more than the appearance of an index page.

I regard these repairs as part of maintaining the tool's usable interface. A reader needs the documented relationship between operations and package contents, even when the interpreter can run the code without that explanation. Keeping the comments attached to their declarations makes that information available through the normal reference workflow.

The update also carries a Bundler version

The release's other stated enhancement installs Bundler 2.3.10 as a default gem. That is a separate tool-distribution change. It should not be confused with the documentation scope fixes or taken as evidence that either patch changes dependency resolution.

The announcement provides the usual RubyGems update command.

gem update --system

That command updates the available RubyGems installation. The documentation repairs concern what its generated API reference exposes, while the bundled version entry concerns which Bundler ships with it. Keeping those claims separate makes the short release notes more informative than a generic statement that the package tools were improved.

The two RDoc patches also identify distinct failure modes. A directive can hide too much because it has the wrong scope. A comment can document too little because intervening code breaks its association with a declaration. RubyGems 3.3.10 corrects both source arrangements, restoring the top-level module reference and the package class example through the existing documentation generator.