update compute_fill_first_cost_fn docstring

The default value for weight of the compute_fill_first_cost_fn is
actually -1.0, which means it does exactly the opposite of what
the function docstring says it does. Update the docstring to
warn people of this fact.

Issue reported via bug #1023827 which was closed as won't fix
but the docs should be clearer. Updated based on feedback.

Change-Id: I56acde254c932a8e66f941aaeb7304665500610f

nova/scheduler/least_cost.py

@@ -79,8 +79,13 @@ def noop_cost_fn(host_state, weighing_properties):
 
 
 def compute_fill_first_cost_fn(host_state, weighing_properties):
-    """More free ram = higher weight. So servers will less free
-    ram will be preferred."""
+    """More free ram = higher weight. So servers with less free
+    ram will be preferred.
+
+    Note: the weight for this function in default configuration
+    is -1.0. With a -1.0 this function runs in reverse, so systems
+    with the most free memory will be preferred.
+    """
     return host_state.free_ram_mb