MONGOID-5555 Avoid duplicating option documentation (#5539)

* Add config introspection to avoid duplicating docs in mongoid.yml template

* update app_spec to look for config options in mongoid.yml

* prefer expectation syntax for consistency's sake

* avoid the eval

* test the full comment, and every config option, for presence in the config file

* don't need to call strip twice

Author: jamis

lib/mongoid/config.rb

@@ -4,6 +4,7 @@
 require "mongoid/config/environment"
 require "mongoid/config/options"
 require "mongoid/config/validators"
+require "mongoid/config/introspection"
 
 module Mongoid
 

lib/mongoid/config/introspection.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Config
+
+    # This module provides a way to inspect not only the defined configuration
+    # settings and their defaults (which are available via
+    # `Mongoid::Config.settings`), but also the documentation about them. It
+    # does this by scraping the `mongoid/config.rb` file with a regular
+    # expression to match comments with options.
+    #
+    # @api private
+    module Introspection
+      extend self
+
+      # A helper class to represent an individual option, its name, its
+      # default value, and the comment that documents it.
+      class Option
+        # The name of this option.
+        #
+        # @return [ String ] The name of the option
+        attr_reader :name
+
+        # The default value of this option.
+        #
+        # @return [ Object ] The default value of the option, typically a
+        #   String, Symbol, nil, true, or false.
+        attr_reader :default
+
+        # The comment that describes this option, as scraped from
+        # mongoid/config.rb.
+        #
+        # @return [ String ] The (possibly multi-line) comment. Each line is
+        #   prefixed with the Ruby comment character ("#").
+        attr_reader :comment
+
+        # Instantiate an option from an array of Regex captures.
+        #
+        # @param [ Array<String> ] captures The array with the Regex captures
+        #   to use to instantiate the option. The element at index 1 must be
+        #   the comment, at index 2 must be the name, and at index 3 must be
+        #   the default value.
+        #
+        # @return [ Option ] The newly instantiated Option object.
+        def self.from_captures(captures)
+          new(captures[2], captures[3], captures[1])
+        end
+
+        # Create a new Option instance with the given name, default value,
+        # and comment.
+        #
+        # @param [ String ] name The option's name.
+        # @param [ String ] default The option's default value, as a String
+        #   representing the actual Ruby value.
+        # @param [ String ] comment The multi-line comment describing the
+        #   option.
+        def initialize(name, default, comment)
+          @name, @default, @comment = name, default, unindent(comment)
+        end
+
+        # Indent the comment by the requested amount, optionally indenting the
+        # first line, as well.
+        #
+        # param [ Integer ] indent The number of spaces to indent each line
+        #   (Default: 2)
+        # param [ true | false ] indent_first_line Whether or not to indent
+        #   the first line of the comment (Default: false)
+        #
+        # @return [ String ] the reformatted comment
+        def indented_comment(indent: 2, indent_first_line: false)
+          comment.gsub(/^/, " " * indent).tap do |result|
+            result.strip! unless indent_first_line
+          end
+        end
+
+        # Reports whether or not the text "(Deprecated)" is present in the
+        # option's comment.
+        #
+        # @return [ true | false ] whether the option is deprecated or not.
+        def deprecated?
+          comment.include?("(Deprecated)")
+        end
+
+        # Compare self with the given option.
+        #
+        # @return [ true | false ] If name, default, and comment are all the
+        #   same, return true. Otherwise, false.
+        def ==(option)
+          name == option.name &&
+            default == option.default &&
+            comment == option.comment
+        end
+
+        private
+
+        # Removes any existing whitespace from the beginning of each line in
+        # the text.
+        #
+        # @param [ String ] text The text to unindent.
+        #
+        # @return [ String ] the unindented text.
+        def unindent(text)
+          text.strip.gsub(/^\s+/, "")
+        end
+      end
+
+      # A regular expression that looks for option declarations of the format:
+      #
+      #   # one or more lines of comments,
+      #   # followed immediately by an option
+      #   # declaration with a default value:
+      #   option :option_name, default: "something"
+      #
+      # The regex produces three captures:
+      #
+      #   1: the (potentially multiline) comment
+      #   2: the option's name
+      #   3: the option's default value
+      OPTION_PATTERN = %r{
+        (
+          ((?:^\s*\#.*\n)+)  # match one or more lines of comments
+          ^\s+option\s+      # followed immediately by a line declaring an option
+          :(\w+),\s+         # match the option's name, followed by a comma
+          default:\s+(.*)    # match the default value for the option
+        \n)                  # end with a newline
+      }x
+
+      # The full path to the source file of the Mongoid::Config module.
+      CONFIG_RB_PATH = File.absolute_path(File.join(
+        File.dirname(__FILE__), "../config.rb"))
+
+      # Extracts the available configuration options from the Mongoid::Config
+      # source file, and returns them as an array of hashes.
+      #
+      # @param [ true | false ] include_deprecated Whether deprecated options
+      #   should be included in the list. (Default: false)
+      #
+      # @return [ Array<Introspection::Option>> ] the array of option objects
+      #   representing each defined option, in alphabetical order by name.
+      def options(include_deprecated: false)
+        src = File.read(CONFIG_RB_PATH)
+        src.scan(OPTION_PATTERN)
+          .map { |opt| Option.from_captures(opt) }
+          .reject { |opt| !include_deprecated && opt.deprecated? }
+          .sort_by { |opt| opt.name }
+      end
+    end
+
+  end
+end

lib/rails/generators/mongoid/config/templates/mongoid.yml

@@ -119,59 +119,11 @@ development:
 
   # Configure Mongoid specific options. (optional)
   options:
-    # Application name that is printed to the mongodb logs upon establishing
-    # a connection in server versions >= 3.4. Note that the name cannot
-    # exceed 128 bytes. It is also used as the database name if the
-    # database name is not explicitly defined. (default: nil)
-    # app_name: MyApplicationName
-    
-    # Mark belongs_to associations as required by default, so that saving a
-    # model with a missing belongs_to association will trigger a validation
-    # error. (default: true)
-    # belongs_to_required_by_default: true
-    
-    # Raise an exception when a field is redefined. (default: false)
-    # duplicate_fields_exception: false
-    
-    # Include the root model name in json serialization. (default: false)
-    # include_root_in_json: false
-
-    # Include the _type field in serialization. (default: false)
-    # include_type_for_serialization: false
-
-    # Whether to join nested persistence contexts for atomic operations
-    # to parent contexts by default. (default: false)
-    # join_contexts: false
-
-    # Set the Mongoid and Ruby driver log levels when Mongoid is not using
-    # Ruby on Rails logger instance. (default: :info)
-    # log_level: :info
-    
-    # Preload all models in development, needed when models use
-    # inheritance. (default: false)
-    # preload_models: false
-
-    # Raise an error when performing a #find and the document is not found.
-    # (default: true)
-    # raise_not_found_error: true
-
-    # Raise an error when defining a scope with the same name as an
-    # existing method. (default: false)
-    # scope_overwrite_exception: false
-
-    # Use ActiveSupport's time zone in time operations instead of
-    # the Ruby default time zone. See the time zone section below for
-    # further information. (default: true)
-    # use_activesupport_time_zone: true
-
-    # Return stored times as UTC. See the time zone section below for
-    # further information. Most applications should not use this option.
-    # (default: false)
-    # use_utc: false
-
-    # (Deprecated) In MongoDB 4.0 and earlier, set whether to create
-    # indexes in the background by default. (default: false)
-    # background_indexing: false
+<%- Mongoid::Config::Introspection.options.each do |opt| -%>
+    <%= opt.indented_comment(indent: 4) %>
+    # <%= opt.name %>: <%= opt.default %>
+
+<%- end -%>
 
 test:
   clients:

spec/integration/app_spec.rb

@@ -125,8 +125,19 @@ def prepare_new_rails_app(name)
         File.exist?(mongoid_config_file).should be true
 
         config_text = File.read(mongoid_config_file)
-        config_text.should =~ /mongoid_test_config_development/
-        config_text.should =~ /mongoid_test_config_test/
+        expect(config_text).to match /mongoid_test_config_development/
+        expect(config_text).to match /mongoid_test_config_test/
+
+        Mongoid::Config::Introspection.options(include_deprecated: true).each do |opt|
+          if opt.deprecated?
+            # deprecated options should not be included
+            expect(config_text).not_to include "# #{opt.name}:"
+          else
+            block = "    #{opt.indented_comment(indent: 4)}\n" \
+                    "    # #{opt.name}: #{opt.default}\n"
+            expect(config_text).to include block
+          end
+        end
       end
     end
 

spec/mongoid/config/introspection_spec.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe Mongoid::Config::Introspection do
+
+  context "CONFIG_RB_PATH" do
+    it "refers to an actual source file" do
+      expect(File.exist?(Mongoid::Config::Introspection::CONFIG_RB_PATH)).to be true
+    end
+  end
+
+  context "#options" do
+    let(:options) { Mongoid::Config::Introspection.options }
+    let(:all_options) { Mongoid::Config::Introspection.options(include_deprecated: true) }
+    let(:deprecated_options) { all_options.select(&:deprecated?) }
+
+    # NOTE: the "with deprecated options" context tests a configuration option
+    # that is known to be deprecated (see `let(:option_name)`). When this
+    # deprecated option is eventually removed, the "exclude" spec will break.
+    # At that time, update the `:option_name` helper to reference a different
+    # deprecated option (if any), or else skip the specs in this context.
+    context "with deprecated options" do
+      let(:option_name) { "background_indexing" }
+
+      it "should exclude deprecated options by default" do
+        option = options.detect { |opt| opt.name == option_name }
+        expect(option).to be_nil
+      end
+
+      it "deprecated options should be included when requested" do
+        option = all_options.detect { |opt| opt.name == option_name }
+        expect(option).not_to be_nil
+      end
+    end
+
+    Mongoid::Config.defaults.each do |name, default_value|
+      context "for the `#{name}` option" do
+        let(:option) { all_options.detect { |opt| opt.name == name.to_s } }
+        let(:live_option) { options.detect { |opt| opt.name == name.to_s } }
+
+        it "should be parsed by the introspection scraper" do
+          expect(option).not_to be_nil
+          expect(option.default).to be == default_value.inspect
+          expect(option.comment.strip).not_to be_empty
+        end
+
+        it "should be excluded by default if it is deprecated" do
+          if option.deprecated?
+            expect(live_option).to be_nil
+          else
+            expect(live_option).to be == option
+          end
+        end
+      end
+    end
+  end
+
+  describe Mongoid::Config::Introspection::Option do
+    let(:option) do
+      Mongoid::Config::Introspection::Option.new(
+        "name", "default", "   # line 1\n    # line 2\n")
+    end
+
+    context ".from_captures" do
+      it "populates the option's fields" do
+        option = Mongoid::Config::Introspection::Option.from_captures([nil, "# comment", "name", "default"])
+        expect(option.name).to be == "name"
+        expect(option.default).to be == "default"
+        expect(option.comment).to be == "# comment"
+      end
+    end
+
+    context "#initialize" do
+      it "unindents the given comment" do
+        expect(option.name).to be == "name"
+        expect(option.default).to be == "default"
+        expect(option.comment).to be == "# line 1\n# line 2"
+      end
+    end
+
+    context "#indented_comment" do
+      it "has defaults" do
+        expect(option.indented_comment).to be == "# line 1\n  # line 2"
+      end
+
+      it "allows indentation to be specified" do
+        expect(option.indented_comment(indent: 3)).to be == "# line 1\n   # line 2"
+      end
+
+      it "allows the first line to be indented" do
+        expect(option.indented_comment(indent: 3, indent_first_line: true))
+          .to be == "   # line 1\n   # line 2"
+      end
+    end
+
+    context "#deprecated?" do
+      let(:deprecated_option) do
+        Mongoid::Config::Introspection::Option.new(
+          "name", "default", "# this\n# is (Deprecated), yo\n")
+      end
+
+      it "is not deprecated by default" do
+        expect(option.deprecated?).not_to be true
+      end
+
+      it "is deprecated when the comment includes \"(Deprecated)\"" do
+        expect(deprecated_option.deprecated?).to be true
+      end
+    end
+  end
+
+end