Move misplaced documentation into place

YARD was tying all these docs to the Spree module rather than the things
that they were actually supposed to document.

core/app/helpers/spree/store_helper.rb

@@ -1,8 +1,8 @@
-# Methods added to this helper will be available to all templates in the frontend.
 module Spree
+  # Methods added to this helper will be available to all templates in the
+  # frontend.
   module StoreHelper
-
-    # helper to determine if its appropriate to show the store menu
+    # @return [Boolean] true when it is appropriate to show the store menu
     def store_menu?
       %w{thank_you}.exclude? params[:action]
     end

core/app/models/spree/adjustment.rb

@@ -1,26 +1,27 @@
-# Adjustments represent a change to the +item_total+ of an Order. Each adjustment
-# has an +amount+ that can be either positive or negative.
-#
-# Adjustments can be "opened" or "closed".
-# Once an adjustment is closed, it will not be automatically updated.
-#
-# Boolean attributes:
-#
-# +mandatory+
-#
-# If this flag is set to true then it means the the charge is required and will not
-# be removed from the order, even if the amount is zero. In other words a record
-# will be created even if the amount is zero. This is useful for representing things
-# such as shipping and tax charges where you may want to make it explicitly clear
-# that no charge was made for such things.
-#
-# +eligible?+
-#
-# This boolean attributes stores whether this adjustment is currently eligible
-# for its order. Only eligible adjustments count towards the order's adjustment
-# total. This allows an adjustment to be preserved if it becomes ineligible so
-# it might be reinstated.
 module Spree
+  # Adjustments represent a change to the +item_total+ of an Order. Each
+  # adjustment has an +amount+ that can be either positive or negative.
+  #
+  # Adjustments can be "opened" or "closed". Once an adjustment is closed, it
+  # will not be automatically updated.
+  #
+  # == Boolean attributes
+  #
+  # 1. *mandatory*
+  #
+  #    If this flag is set to true then it means the the charge is required and
+  #    will not be removed from the order, even if the amount is zero. In other
+  #    words a record will be created even if the amount is zero. This is
+  #    useful for representing things such as shipping and tax charges where
+  #    you may want to make it explicitly clear that no charge was made for
+  #    such things.
+  #
+  # 2. *eligible?*
+  #
+  #    This boolean attributes stores whether this adjustment is currently
+  #    eligible for its order. Only eligible adjustments count towards the
+  #    order's adjustment total. This allows an adjustment to be preserved if
+  #    it becomes ineligible so it might be reinstated.
   class Adjustment < Spree::Base
     belongs_to :adjustable, polymorphic: true, touch: true
     belongs_to :source, polymorphic: true

core/app/models/spree/calculator/free_shipping.rb

@@ -1,8 +1,7 @@
-# TODO: Deprecate this class.
-# This calculator will be removed in future versions of Spree.
-# The only case where it was used was for Free Shipping Promotions.
-# There is now a Promotion Action which deals with these types of promotions instead.
 module Spree
+  # @deprecated This calculator will be removed in future versions of Spree.
+  #   The only case where it was used was for Free Shipping Promotions.  There is
+  #   now a Promotion Action which deals with these types of promotions instead.
   class Calculator::FreeShipping < Calculator
     def self.description
       Spree.t(:free_shipping)
@@ -19,4 +18,4 @@ def compute(object)
       order.ship_total
     end
   end
-end
+end

core/app/models/spree/gateway/bogus_simple.rb

@@ -1,5 +1,5 @@
-# Bogus Gateway that doesn't support payment profiles
 module Spree
+  # Bogus Gateway that doesn't support payment profiles.
   class Gateway::BogusSimple < Gateway::Bogus
 
     def payment_profiles_supported?

core/app/models/spree/legacy_user.rb

@@ -1,5 +1,8 @@
-# Default implementation of User.  This class is intended to be modified by extensions (ex. spree_auth_devise)
 module Spree
+  # Default implementation of User.
+  #
+  # @note This class is intended to be modified by extensions (ex.
+  #   spree_auth_devise)
   class LegacyUser < Spree::Base
     include UserAddress
     include UserPaymentSource

core/app/models/spree/order_promotion.rb

@@ -1,7 +1,8 @@
-# Spree::OrderPromotion represents the relationship between:
-# 1. A promotion that a user attempted to apply to their order
-# 2. The specific code that they used
 module Spree
+  # Spree::OrderPromotion represents the relationship between:
+  #
+  # 1. A promotion that a user attempted to apply to their order
+  # 2. The specific code that they used
   class OrderPromotion < ActiveRecord::Base
     self.table_name = 'spree_orders_promotions'
 

core/app/models/spree/promotion/rules/item_total.rb

@@ -1,8 +1,8 @@
-# A rule to apply to an order greater than (or greater than or equal to)
-# a specific amount
 module Spree
   class Promotion
     module Rules
+      # A rule to apply to an order greater than (or greater than or equal to)
+      # a specific amount
       class ItemTotal < PromotionRule
         preference :amount_min, :decimal, default: 100.00
         preference :operator_min, :string, default: '>'

core/app/models/spree/promotion/rules/product.rb

@@ -1,9 +1,10 @@
-# A rule to limit a promotion based on products in the order.
-# Can require all or any of the products to be present.
-# Valid products either come from assigned product group or are assingned directly to the rule.
 module Spree
   class Promotion
     module Rules
+      # A rule to limit a promotion based on products in the order.  Can
+      # require all or any of the products to be present.  Valid products
+      # either come from assigned product group or are assingned directly to
+      # the rule.
       class Product < PromotionRule
         has_and_belongs_to_many :products, class_name: '::Spree::Product', join_table: 'spree_products_promotion_rules', foreign_key: 'promotion_rule_id'
 

core/app/models/spree/promotion_action.rb

@@ -1,17 +1,21 @@
-# Base class for all types of promotion action.
-# PromotionActions perform the necessary tasks when a promotion is activated by an event and determined to be eligible.
 module Spree
+  # Base class for all types of promotion action.
+  #
+  # PromotionActions perform the necessary tasks when a promotion is activated
+  # by an event and determined to be eligible.
   class PromotionAction < Spree::Base
     acts_as_paranoid
 
     belongs_to :promotion, class_name: 'Spree::Promotion'
 
     scope :of_type, ->(t) { where(type: t) }
 
-    # This method should be overriden in subclass
-    # Updates the state of the order or performs some other action depending on the subclass
-    # options will contain the payload from the event that activated the promotion. This will include
-    # the key :user which allows user based actions to be performed in addition to actions on the order
+    # Updates the state of the order or performs some other action depending on
+    # the subclass options will contain the payload from the event that
+    # activated the promotion. This will include the key :user which allows
+    # user based actions to be performed in addition to actions on the order
+    #
+    # @note This method should be overriden in subclassses.
     def perform(options = {})
       raise 'perform should be implemented in a sub-class of PromotionAction'
     end

core/app/models/spree/promotion_rule.rb

@@ -1,5 +1,5 @@
-# Base class for all promotion rules
 module Spree
+  # Base class for all promotion rules
   class PromotionRule < Spree::Base
     belongs_to :promotion, class_name: 'Spree::Promotion', inverse_of: :promotion_rules
 

core/app/models/spree/stock/adjuster.rb

@@ -1,7 +1,8 @@
-# Used by Prioritizer to adjust item quantities
-# see prioritizer_spec for use cases
 module Spree
   module Stock
+    # Used by Prioritizer to adjust item quantities.
+    #
+    # See spec/models/spree/stock/prioritizer_spec.rb for use cases.
     class Adjuster
       attr_accessor :inventory_unit, :status, :fulfilled
 

core/lib/spree/testing_support/controller_requests.rb

@@ -1,30 +1,29 @@
-# Use this module to easily test Spree actions within Spree components
-# or inside your application to test routes for the mounted Spree engine.
-#
-# Inside your spec_helper.rb, include this module inside the RSpec.configure
-# block by doing this:
-#
-#   require 'spree/testing_support/controller_requests'
-#   RSpec.configure do |c|
-#     c.include Spree::TestingSupport::ControllerRequests, :type => :controller
-#   end
-#
-# Then, in your controller tests, you can access spree routes like this:
-#
-#   require 'spec_helper'
-#
-#   describe Spree::ProductsController do
-#     it "can see all the products" do
-#       spree_get :index
-#     end
-#   end
-#
-# Use spree_get, spree_post, spree_put or spree_delete to make requests
-# to the Spree engine, and use regular get, post, put or delete to make
-# requests to your application.
-#
 module Spree
   module TestingSupport
+    # Use this module to easily test Spree actions within Spree components or
+    # inside your application to test routes for the mounted Spree engine.
+    #
+    # Inside your spec_helper.rb, include this module inside the
+    # RSpec.configure block by doing this:
+    #
+    #   require 'spree/testing_support/controller_requests'
+    #   RSpec.configure do |c|
+    #     c.include Spree::TestingSupport::ControllerRequests, :type => :controller
+    #   end
+    #
+    # Then, in your controller tests, you can access spree routes like this:
+    #
+    #   require 'spec_helper'
+    #
+    #   describe Spree::ProductsController do
+    #     it "can see all the products" do
+    #       spree_get :index
+    #     end
+    #   end
+    #
+    # Use spree_get, spree_post, spree_put or spree_delete to make requests to
+    # the Spree engine, and use regular get, post, put or delete to make
+    # requests to your application.
     module ControllerRequests
       def spree_get(action, parameters = nil, session = nil, flash = nil)
         process_spree_action(action, parameters, session, flash, "GET")

core/lib/spree/testing_support/i18n.rb

@@ -1,13 +1,14 @@
-# This file exists solely to test whether or not there are missing translations
-# within the code that Spree's test suite covers.
-#
-# If there is a translation referenced which has no corresponding key within the
-# .yml file, then there will be a message output at the end of the suite showing
-# that.
-#
-# If there is a translation within the locale file which *isn't* used in the
-# test, this will also be shown at the end of the suite run.
 module Spree
+  # This file exists solely to test whether or not there are missing translations
+  # within the code that Spree's test suite covers.
+  #
+  # If there is a translation referenced which has no corresponding key within the
+  # .yml file, then there will be a message output at the end of the suite showing
+  # that.
+  #
+  # If there is a translation within the locale file which *isn't* used in the
+  # test, this will also be shown at the end of the suite run.
+
   class << self
     attr_accessor :used_translations, :missing_translation_messages,
                   :unused_translations, :unused_translation_messages