Doc coverage.

* Many things are private.
* Added docs tend to be terrible, I don't have enough context to flesh
  them out.
* Still some warnings in here I don't know what to do about.
* What do we do about CI? Can rspec-dev add it for us?

Author: xaviershay

lib/generators/rspec.rb

@@ -1,7 +1,11 @@
 require 'rails/generators/named_base'
 
+# Weirdly named generators namespace (should be `RSpec`) for compatability with
+# rails loading.
 module Rspec
+  # @private
   module Generators
+    # @private
     class Base < ::Rails::Generators::NamedBase
       def self.source_root
         @_rspec_source_root ||= File.expand_path(File.join(File.dirname(__FILE__), 'rspec', generator_name, 'templates'))
@@ -16,8 +20,10 @@ def module_namespacing
   end
 end
 
+# @private
 module Rails
   module Generators
+    # @private
     class GeneratedAttribute
       def input_type
         @input_type ||= if type == :text

lib/generators/rspec/controller/controller_generator.rb

@@ -2,6 +2,7 @@
 
 module Rspec
   module Generators
+    # @private
     class ControllerGenerator < Base
       argument :actions, :type => :array, :default => [], :banner => "action action"
 

lib/generators/rspec/feature/feature_generator.rb

@@ -2,6 +2,7 @@
 
 module Rspec
   module Generators
+    # @private
     class FeatureGenerator < Base
       class_option :feature_specs, :type => :boolean, :default => true, :desc => "Generate feature specs"
 

lib/generators/rspec/helper/helper_generator.rb

@@ -2,6 +2,7 @@
 
 module Rspec
   module Generators
+    # @private
     class HelperGenerator < Base
       class_option :helper_specs, :type => :boolean, :default => true
 

lib/generators/rspec/install/install_generator.rb

@@ -1,5 +1,6 @@
 module Rspec
   module Generators
+    # @private
     class InstallGenerator < ::Rails::Generators::Base
 
       desc <<DESC

lib/generators/rspec/integration/integration_generator.rb

@@ -2,6 +2,7 @@
 
 module Rspec
   module Generators
+    # @private
     class IntegrationGenerator < Base
       class_option :request_specs,   :type => :boolean, :default => true,  :desc => "Generate request specs"
 

lib/generators/rspec/mailer/mailer_generator.rb

@@ -2,6 +2,7 @@
 
 module Rspec
   module Generators
+    # @private
     class MailerGenerator < Base
       argument :actions, :type => :array, :default => [], :banner => "method method"
 

lib/generators/rspec/model/model_generator.rb

@@ -2,6 +2,7 @@
 
 module Rspec
   module Generators
+    # @private
     class ModelGenerator < Base
       argument :attributes, :type => :array, :default => [], :banner => "field:type field:type"
       class_option :fixture, :type => :boolean

lib/generators/rspec/observer/observer_generator.rb

@@ -2,6 +2,7 @@
 
 module Rspec
   module Generators
+    # @private
     class ObserverGenerator < Base
       def generate_observer_spec
         template 'observer_spec.rb',

lib/generators/rspec/scaffold/scaffold_generator.rb

@@ -3,6 +3,7 @@
 
 module Rspec
   module Generators
+    # @private
     class ScaffoldGenerator < Base
       include ::Rails::Generators::ResourceHelpers
       source_paths << File.expand_path("../../helper/templates", __FILE__)

lib/generators/rspec/view/view_generator.rb

@@ -2,6 +2,7 @@
 
 module Rspec
   module Generators
+    # @private
     class ViewGenerator < Base
       argument :actions, :type => :array, :default => [], :banner => "action action"
 

lib/rspec-rails.rb

@@ -1,5 +1,8 @@
+# Namespace for all core RSpec projects.
 module RSpec
+  # Namespace for rspec-rails code.
   module Rails
+    # Railtie to hook into Rails.
     class Railtie < ::Rails::Railtie
       # Rails-3.0.1 requires config.app_generators instead of 3.0.0's config.generators
       generators = config.respond_to?(:app_generators) ? config.app_generators : config.generators

lib/rspec/rails/adapters.rb

@@ -7,6 +7,8 @@ module Rails
     if ::Rails::VERSION::STRING >= '4.1.0'
       gem 'minitest'
       require 'minitest/assertions'
+      # Constant aliased to either Minitest or TestUnit, depending on what is
+      # loaded.
       Assertions = Minitest::Assertions
     else
       begin
@@ -16,12 +18,13 @@ module Rails
         require 'rubysl-test-unit' if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx'
         require 'test/unit/assertions'
       end
+      # Constant aliased to either Minitest or TestUnit, depending on what is
+      # loaded.
       Assertions = Test::Unit::Assertions
     end
 
-    # @api private
+    # @private
     class AssertionDelegator < Module
-      # @api private
       def initialize(*assertion_modules)
         assertion_class = Class.new(SimpleDelegator) do
           include ::RSpec::Rails::Assertions
@@ -30,12 +33,10 @@ def initialize(*assertion_modules)
         end
 
         super() do
-          # @api private
           define_method :build_assertion_instance do
             assertion_class.new(self)
           end
 
-          # @api private
           def assertion_instance
             @assertion_instance ||= build_assertion_instance
           end
@@ -54,7 +55,7 @@ def assertion_instance
 
     # Adapts example groups for `Minitest::Test::LifecycleHooks`
     #
-    # @api private
+    # @private
     module MinitestLifecycleAdapter
       extend ActiveSupport::Concern
 
@@ -82,26 +83,22 @@ def after_teardown
       end
     end
 
-    # @api private
+    # @private
     module MinitestCounters
-      # @api private
       def assertions
         @assertions ||= 0
       end
 
-      # @api private
       def assertions=(assertions)
         @assertions = assertions
       end
     end
 
-    # @api private
+    # @private
     module SetupAndTeardownAdapter
       extend ActiveSupport::Concern
 
       module ClassMethods
-        # @api private
-        #
         # Wraps `setup` calls from within Rails' testing framework in `before`
         # hooks.
         def setup(*methods)
@@ -123,7 +120,6 @@ def teardown(*methods)
         end
       end
 
-      # @api private
       def method_name
         @example
       end
@@ -133,9 +129,8 @@ def method_name
     module MinitestAssertionAdapter
       extend ActiveSupport::Concern
 
+      # @private
       module ClassMethods
-        # @api private
-        #
         # Returns the names of assertion methods that we want to expose to
         # examples without exposing non-assertion methods in Test::Unit or
         # Minitest.
@@ -144,7 +139,6 @@ def assertion_method_names
             [:build_message]
         end
 
-        # @api private
         def define_assertion_delegators
           assertion_method_names.each do |m|
             define_method(m.to_sym) do |*args, &block|
@@ -154,13 +148,11 @@ def define_assertion_delegators
         end
       end
 
-      # @api private
       class AssertionDelegator
         include ::RSpec::Rails::Assertions
         include ::RSpec::Rails::MinitestCounters
       end
 
-      # @api private
       def assertion_delegator
         @assertion_delegator ||= AssertionDelegator.new
       end
@@ -173,7 +165,7 @@ def assertion_delegator
     # Backwards compatibility. It's unlikely that anyone is using this
     # constant, but we had forgotten to mark it as `@private` earlier
     #
-    # @api private
+    # @private
     TestUnitAssertionAdapter = MinitestAssertionAdapter
   end
 end

lib/rspec/rails/configuration.rb

@@ -13,7 +13,7 @@ def self.initialize_configuration(config)
       config.include RSpec::Rails::ViewExampleGroup,       :type => :view
       config.include RSpec::Rails::FeatureExampleGroup,    :type => :feature
 
-      if defined?(RSpec::Rails::MailerExampleGroup)
+      if defined?(ActionMailer)
         config.include RSpec::Rails::MailerExampleGroup, :type => :mailer
       end
 
@@ -36,18 +36,26 @@ def self.initialize_configuration(config)
       # but requires this workaround:
       config.add_setting :rendering_views, :default => false
 
+      # @private
+      # TODO: How to YARD this? Not actually private.
       def config.render_views=(val)
         self.rendering_views = val
       end
 
+      # @private
+      # TODO: How to YARD this? Not actually private.
       def config.render_views
         self.rendering_views = true
       end
 
+      # @private
+      # TODO: How to YARD this? Not actually private.
       def config.render_views?
         rendering_views
       end
 
+      # @private
+      # TODO: How to YARD this? Not actually private.
       def config.infer_spec_type_from_file_location!
         {
           :controller => %w[spec controllers],

lib/rspec/rails/example/controller_example_group.rb

@@ -1,4 +1,5 @@
 module RSpec::Rails
+  # Container module for controller spec functionality.
   module ControllerExampleGroup
     extend ActiveSupport::Concern
     include RSpec::Rails::RailsExampleGroup
@@ -9,6 +10,7 @@ module ControllerExampleGroup
     include RSpec::Rails::Matchers::RoutingMatchers
     include RSpec::Rails::AssertionDelegator.new(ActionDispatch::Assertions::RoutingAssertions)
 
+    # Class-level DSL for controller specs.
     module ClassMethods
       # @private
       def controller_class
@@ -28,7 +30,6 @@ def controller_class
       #   within the block.
       #
       # @example
-      #
       #     describe ApplicationController do
       #       controller do
       #         def index
@@ -97,7 +98,6 @@ def self.name
       # is most useful when testing Rails engines.
       #
       # @example
-      #
       #     describe MyEngine::PostsController do
       #       routes { MyEngine::Engine.routes }
       #
@@ -112,12 +112,13 @@ def routes(&blk)
 
     attr_reader :controller, :routes
 
-    # @api private
+    # @private
     def routes=(routes)
       @routes = routes
       assertion_instance.instance_variable_set(:@routes, routes)
     end
 
+    # @private
     module BypassRescue
       def rescue_with_handler(exception)
         raise exception
@@ -130,7 +131,6 @@ def rescue_with_handler(exception)
     # conditions.
     #
     # @example
-    #
     #     describe ProfilesController do
     #       it "raises a 403 when a non-admin user tries to view another user's profile" do
     #         profile = create_profile

lib/rspec/rails/example/feature_example_group.rb

@@ -1,8 +1,10 @@
 module RSpec::Rails
+  # Container module for routing spec functionality.
   module FeatureExampleGroup
     extend ActiveSupport::Concern
     include RSpec::Rails::RailsExampleGroup
 
+    # Default host to be used in Rails route helpers if none is specified.
     DEFAULT_HOST = "www.example.com"
 
     included do
@@ -17,6 +19,9 @@ module FeatureExampleGroup
       end
     end
 
+    # Shim to check for presence of Capybara. Will delegate if present, raise
+    # if not. We assume here that in most cases `visit` will be the first
+    # Capybara method called in a spec.
     def visit(*)
       if defined?(super)
         super

lib/rspec/rails/example/helper_example_group.rb

@@ -1,14 +1,15 @@
 require 'rspec/rails/view_assigns'
 
 module RSpec::Rails
+  # Container module for helper specs.
   module HelperExampleGroup
     extend ActiveSupport::Concern
     include RSpec::Rails::RailsExampleGroup
     include ActionView::TestCase::Behavior
     include RSpec::Rails::ViewAssigns
 
+    # @private
     module ClassMethods
-      # @api private
       def determine_default_helper_class(ignore)
         described_class
       end