Ensure expect, should and should_not are doc'd properly.

They should be doc'd as part of `RSpec::Matchers` and
`BasicObject`, not part of `RSpec::Expectations::Syntax`.

lib/rspec/expectations/syntax.rb

@@ -6,37 +6,6 @@ module Expectations
     module Syntax
       module_function
 
-      # @method should
-      # Passes if `matcher` returns true.  Available on every `Object`.
-      # @example
-      #   actual.should eq expected
-      #   actual.should match /expression/
-      # @param [Matcher]
-      #   matcher
-      # @param [String] message optional message to display when the expectation fails
-      # @return [Boolean] true if the expectation succeeds (else raises)
-      # @see RSpec::Matchers
-
-      # @method should_not
-      # Passes if `matcher` returns false.  Available on every `Object`.
-      # @example
-      #   actual.should_not eq expected
-      # @param [Matcher]
-      #   matcher
-      # @param [String] message optional message to display when the expectation fails
-      # @return [Boolean] false if the negative expectation succeeds (else raises)
-      # @see RSpec::Matchers
-
-      # @method expect
-      # Supports `expect(actual).to matcher` syntax by wrapping `actual` in an
-      # `ExpectationTarget`.
-      # @example
-      #   expect(actual).to eq(expected)
-      #   expect(actual).not_to eq(expected)
-      # @return [ExpectationTarget]
-      # @see ExpectationTarget#to
-      # @see ExpectationTarget#not_to
-
       # @api private
       # Determines where we add `should` and `should_not`.
       def default_should_host
@@ -132,3 +101,32 @@ def expect_enabled?(syntax_host = ::RSpec::Matchers)
     end
   end
 end
+
+# The legacy `:should` syntax adds the following methods directly to
+# `BasicObject` so that they are available off of any object. Note, however,
+# that this syntax does not always play nice with delegate/proxy objects.
+# We recommend you use the non-monkeypatching `:expect` syntax instead.
+class BasicObject
+  # @method should
+  # Passes if `matcher` returns true.  Available on every `Object`.
+  # @example
+  #   actual.should eq expected
+  #   actual.should match /expression/
+  # @param [Matcher]
+  #   matcher
+  # @param [String] message optional message to display when the expectation fails
+  # @return [Boolean] true if the expectation succeeds (else raises)
+  # @note This is only available when you have enabled the `:should` syntax.
+  # @see RSpec::Matchers
+
+  # @method should_not
+  # Passes if `matcher` returns false.  Available on every `Object`.
+  # @example
+  #   actual.should_not eq expected
+  # @param [Matcher]
+  #   matcher
+  # @param [String] message optional message to display when the expectation fails
+  # @return [Boolean] false if the negative expectation succeeds (else raises)
+  # @note This is only available when you have enabled the `:should` syntax.
+  # @see RSpec::Matchers
+end

lib/rspec/matchers.rb

@@ -209,6 +209,16 @@ module RSpec
   # for readable failure messages. You can alias your custom matchers in similar fashion
   # using {RSpec::Matchers.alias_matcher}.
   module Matchers
+    # @method expect
+    # Supports `expect(actual).to matcher` syntax by wrapping `actual` in an
+    # `ExpectationTarget`.
+    # @example
+    #   expect(actual).to eq(expected)
+    #   expect(actual).not_to eq(expected)
+    # @return [ExpectationTarget]
+    # @see ExpectationTarget#to
+    # @see ExpectationTarget#not_to
+
     # Defines a matcher alias. The returned matcher's `description` will be overriden
     # to reflect the phrasing of the new name, which will be used in failure messages
     # when passed as an argument to another matcher in a composed matcher expression.