(core) Update documentation of certain functions

Summary:
- lookupOne/lookupRecords explain `sort_by` param better, and
  link to more detailed article.
- Incorporate a typo fix from Help Center
- Fix the omission of TASTEME never having been documented.

Test Plan: Corresponding update to Help Center can be reviewed at https://github.com/gristlabs/grist-help/pull/351

Reviewers: jarek

Reviewed By: jarek

Subscribers: jarek

Differential Revision: https://phab.getgrist.com/D4269

sandbox/grist/functions/text.py

@@ -647,6 +647,18 @@ def T(value):
           six.text_type(value) if isinstance(value, AltText) else u"")
 
 def TASTEME(food):
+  """
+  For any given piece of text, decides if it is tasty or not.
+
+  This is not serious. It appeared as an Easter egg, and is kept as such. It is in fact a puzzle
+  to figure out the underlying simple rule. It has been surprisingly rarely cracked, even after
+  reading the source code, which is freely available and may entertain Python fans.
+
+  >>> TASTEME('Banana')
+  True
+  >>> TASTEME('Garlic')
+  False
+  """
   chews = re.findall(r'\b[A-Z]+\b', food.upper())
   claw = slice(2, None)
   spit = lambda chow: chow[claw]
@@ -657,9 +669,9 @@ def TASTEME(food):
 @unimplemented
 def TEXT(number, format_type):    # pylint: disable=unused-argument
   """
-  Converts a number into text according to a specified format. It is not yet implemented in 
+  Converts a number into text according to a specified format. It is not yet implemented in
   Grist. You can use the similar Python functions str() to convert numbers into strings, and
-  optionally format() to specify the number format. 
+  optionally format() to specify the number format.
   """
   raise NotImplementedError()
 
@@ -681,7 +693,7 @@ def TRIM(text):
 
 def UPPER(text):
   """
-  Converts a specified string to uppercase. Same as `text.lower()`.
+  Converts a specified string to uppercase. Same as `text.upper()`.
 
   >>> UPPER("e. e. cummings")
   'E. E. CUMMINGS'

sandbox/grist/table.py

@@ -68,13 +68,17 @@ class UserTable(object):
     any expression,
     most commonly a field in the current row (e.g. `$SomeField`) or a constant (e.g. a quoted string
     like `"Some Value"`) (examples below).
-    If `sort_by=field` is given, sort the results by that field.
+
+    You may set the optional `sort_by` parameter to the column ID by which to sort multiple matching
+    results, to determine which of them is returned. You can prefix the column ID with "-" to
+    reverse the order.
 
     For example:
     ```
     People.lookupRecords(Email=$Work_Email)
     People.lookupRecords(First_Name="George", Last_Name="Washington")
     People.lookupRecords(Last_Name="Johnson", sort_by="First_Name")
+    Orders.lookupRecords(Customer=$id, sort_by="-OrderDate")
     ```
 
     See [RecordSet](#recordset) for useful properties offered by the returned object.
@@ -82,6 +86,8 @@ class UserTable(object):
     See [CONTAINS](#contains) for an example utilizing `UserTable.lookupRecords` to find records
     where a field of a list type (such as `Choice List` or `Reference List`) contains the given
     value.
+
+    Learn more about [lookupRecords](references-lookups.md#lookuprecords).
     """
     return self.table.lookup_records(**field_value_pairs)
 
@@ -92,14 +98,21 @@ class UserTable(object):
     Returns a [Record](#record) matching the given field=value arguments. The value may be any
     expression,
     most commonly a field in the current row (e.g. `$SomeField`) or a constant (e.g. a quoted string
-    like `"Some Value"`). If multiple records match, returns one of them. If none match, returns the
+    like `"Some Value"`). If multiple records are found, the first match is returned.
-    special empty record.
+
+    You may set the optional `sort_by` parameter to the column ID by which to sort multiple matching
+    results, to determine which of them is returned. You can prefix the column ID with "-" to
+    reverse the order.
 
     For example:
     ```
     People.lookupOne(First_Name="Lewis", Last_Name="Carroll")
     People.lookupOne(Email=$Work_Email)
+    Tickets.lookupOne(Person=$id, sort_by="Date")   # Find the first ticket for the person
+    Tickets.lookupOne(Person=$id, sort_by="-Date")  # Find the last ticket for the person
     ```
+
+    Learn more about [lookupOne](references-lookups.md#lookupone).
     """
     return self.table.lookup_one_record(**field_value_pairs)