api-ref: document caveats with scheduler hints

I noticed this while working on change
I49ffebcd129990f1835f404d98b51732a32171eb and I realized
the scheduler_hints in the legacy filter_properties
dict is a bit different than what's in the RequestSpec
object, namely that the request validation schema is
per-hint. Some require a single value, like 'group', and
some accept a list of values, like 'different_host'.

Given how nebulous scheduler hints are, we should probably
note these in the API reference for the parameter, especially
because scheduler hints should not be considered interoperable.

Change-Id: I74114fc56bee2bebf4a5f5d6823ec968cad9a8e9

api-ref/source/parameters.yaml

@@ -4436,7 +4436,19 @@ os-stop:
 os:scheduler_hints:
   description: |
     The dictionary of data to send to the scheduler. Alternatively, you can specify
-    ``OS-SCH-HNT:scheduler_hints`` as the string.
+    ``OS-SCH-HNT:scheduler_hints`` as the key in the request body.
+
+    There are a few caveats with scheduler hints:
+
+    * The request validation schema is per hint. For example, some require a
+      single string value, and some accept a list of values.
+    * Hints are only used based on the cloud scheduler configuration, which
+      varies per deployment.
+    * Hints are pluggable per deployment, meaning that a cloud can have custom
+      hints which may not be available in another cloud.
+
+    For these reasons, it is important to consult each cloud's user
+    documentation to know what is available for scheduler hints.
   in: body
   required: false
   type: object

nova/api/openstack/compute/schemas/scheduler_hints.py

@@ -39,7 +39,7 @@ _hints = {
             ]
         },
         'same_host': {
-            # NOTE: The value of 'different_host' is the set of server
+            # NOTE: The value of 'same_host' is the set of server
             # uuids where a new server is scheduled on the same host.
             'type': ['string', 'array'],
             'items': parameter_types.server_id