From 25b7e6c2455864f6fee047dda67fc0e4a2172b26 Mon Sep 17 00:00:00 2001 From: Dmitry Date: Sun, 13 Feb 2022 00:45:24 -0500 Subject: [PATCH] Tweaks to documentation comments for user-facing Grist functions (#126) - Update internal links in function documentation - Remove emphasis in code blocks - Remove trailing whitespace --- sandbox/grist/functions/math.py | 10 +++++----- sandbox/grist/functions/text.py | 6 +++--- sandbox/grist/records.py | 4 ++-- sandbox/grist/table.py | 22 +++++++++++----------- 4 files changed, 21 insertions(+), 21 deletions(-) diff --git a/sandbox/grist/functions/math.py b/sandbox/grist/functions/math.py index 3ea3128a..e508fc62 100644 --- a/sandbox/grist/functions/math.py +++ b/sandbox/grist/functions/math.py @@ -797,7 +797,7 @@ def SUMIFS(sum_range, criteria_range1, criterion1, *args): def SUMPRODUCT(array1, *more_arrays): """ - Multiplies corresponding components in two equally-sized arrays, + Multiplies corresponding components in two equally-sized arrays, and returns the sum of those products. >>> SUMPRODUCT([3,8,1,4,6,9], [2,6,5,7,7,3]) @@ -861,10 +861,10 @@ def TRUNC(value, places=0): def UUID(): """ - Generate a random UUID-formatted string identifier. - Since UUID() produces a different value each time it's called, it is best to use it in - [trigger formula](https://support.getgrist.com/formulas/#trigger-formulas) for new records. - This would only calculate UUID() once and freeze the calculated value. By contrast, a regular [formula] + Generate a random UUID-formatted string identifier. + Since UUID() produces a different value each time it's called, it is best to use it in + [trigger formula](formulas.md#trigger-formulas) for new records. + This would only calculate UUID() once and freeze the calculated value. By contrast, a regular formula may get recalculated any time the document is reloaded, producing a different value for UUID() each time. """ if six.PY2: diff --git a/sandbox/grist/functions/text.py b/sandbox/grist/functions/text.py index 68c1bb69..608bf0e9 100644 --- a/sandbox/grist/functions/text.py +++ b/sandbox/grist/functions/text.py @@ -220,9 +220,9 @@ def LEFT(string, num_chars=1): def LEN(text): """ - Returns the number of characters in a text string, or the number of items in a list. Same as - [`len`](https://docs.python.org/3/library/functions.html#len) in python. - See [Record Set](https://support.getgrist.com/functions/#recordset) for an example of using `len` on a list of records. + Returns the number of characters in a text string, or the number of items in a list. Same as + [`len`](https://docs.python.org/3/library/functions.html#len) in python. + See [Record Set](#recordset) for an example of using `len` on a list of records. >>> LEN("Phoenix, AZ") 11 diff --git a/sandbox/grist/records.py b/sandbox/grist/records.py index 2d68cbfd..7fd478c4 100644 --- a/sandbox/grist/records.py +++ b/sandbox/grist/records.py @@ -38,8 +38,8 @@ class Record(object): Name: $group, rec.group Usage: __$group__ - In a [summary table](https://support.getgrist.com/summary-tables/), `$group` is a special field - containing the list of Records that are summarized by the current summary line. E.g. the formula + In a [summary table](summary-tables.md), `$group` is a special field + containing the list of Records that are summarized by the current summary line. E.g. the formula `len($group)` counts the number of those records being summarized in each row. See [RecordSet](#recordset) for useful properties offered by the returned object. diff --git a/sandbox/grist/table.py b/sandbox/grist/table.py index ef0f7209..9ea30c19 100644 --- a/sandbox/grist/table.py +++ b/sandbox/grist/table.py @@ -81,16 +81,16 @@ class UserTable(object): """ Name: lookupRecords Usage: UserTable.__lookupRecords__(Field_In_Lookup_Table=value, ...) - Returns a RecordSet 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"`) (examples below). + Returns a [RecordSet](#recordset) 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"`) (examples below). If `sort_by=field` is given, sort the results by that field. For example: ``` - People.*lookupRecords*(Email=$Work_Email) - People.*lookupRecords*(First_Name="George", Last_Name="Washington") - People.*lookupRecords*(Last_Name="Johnson", sort_by="First_Name") + People.lookupRecords(Email=$Work_Email) + People.lookupRecords(First_Name="George", Last_Name="Washington") + People.lookupRecords(Last_Name="Johnson", sort_by="First_Name") ``` See [RecordSet](#recordset) for useful properties offered by the returned object. @@ -105,15 +105,15 @@ class UserTable(object): """ Name: lookupOne Usage: UserTable.__lookupOne__(Field_In_Lookup_Table=value, ...) - Returns a 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 + 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 special empty record. For example: ``` - People.*lookupOne*(First_Name="Lewis", Last_Name="Carroll") - People.*lookupOne*(Email=$Work_Email) + People.lookupOne(First_Name="Lewis", Last_Name="Carroll") + People.lookupOne(Email=$Work_Email) ``` """ return self.table.lookup_one_record(**field_value_pairs)