Apply suggestions from code review

Co-authored-by: James McKinney <26463+jpmckinney@users.noreply.github.com>

docs/changelog.rst

@@ -7,7 +7,7 @@ Changelog
 Changed
 ~~~~~~~
 
-- ``field_list`` field now a JSONB with keys as the path and values as NULL
+-  The ``field_list`` column is now a JSONB object in which keys are paths and values are ``NULL``
 
 
 2020-12-09

docs/cli/use.rst

@@ -80,10 +80,10 @@ Use this option if:
 
 .. _field-lists:
 
-Create JSON of all paths for each row in each summary table
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Calculate JSON paths in each JSON object in each summary table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``--field_lists`` option adds a ``field_list`` column to each summary table, which contains a JSONB object of all JSON paths (excluding array indices) in the object that the row describes. For example, a ``field_list`` value in the ``awards_summary`` table will contain the JSON paths in an award object. The keys of the ``field-list`` JSONB object are the path and the values are NULL.
+The ``--field_lists`` option adds a ``field_list`` column to each summary table, which contains all JSON paths (excluding array indices) in the object that the row describes. For example, a ``field_list`` value in the ``awards_summary`` table will contain the JSON paths in an award object. A ``field_list`` value is a JSONB object in which keys are paths and values are ``NULL``.
 
 .. code-block:: bash
 
@@ -97,23 +97,27 @@ This can be used to check for the presence of multiple fields.  For example, to
 
    SELECT count(*) FROM view_data_collection_1.awards_summary WHERE field_list ?& ARRAY['documents/id', 'items/id'];
 
-   -- this could also be written as
+This could also be written as:
+
+.. code-block:: sql
 
    SELECT count(*) FROM view_data_collection_1.awards_summary WHERE field_list ? 'documents/id' AND field_list ? 'items/id';
 
-The ``?&`` operator tests whether the left JSON object has all the keys in the right ARRAY values.  The ``?`` operator checks if the key exists in the object.
+The ``?&`` operator tests whether *all* keys in the right-hand array exist in the left-hand object.  The ``?`` operator tests whether one key exists in the left-hand object.
 
-To count the number of awards that have either at least one document with an ``id`` or at least one iten with an ``id``, run:
+To count the number of awards that have either at least one document with an ``id`` or at least one item with an ``id``, run:
 
 .. code-block:: sql
 
    SELECT count(*) FROM view_data_collection_1.awards_summary WHERE field_list ?| ARRAY['documents/id', 'items/id'];
 
-   -- this could also be written as
+This could also be written as:
+
+.. code-block:: sql
 
    SELECT count(*) FROM view_data_collection_1.awards_summary WHERE field_list ? 'documents/id' OR field_list ? 'items/id';
 
-The ``?|`` operator tests whether the left JSON object has any of the keys in the right ARRAY values.
+The ``?|`` operator tests whether *any* key in the right-hand array exists in the left-hand object.
 
 .. _remove:
 

manage.py

@@ -561,8 +561,8 @@ def _add_field_list_comments(summary_table, name):
     for row in db.all(statement, {'schema': name, 'table': f'{summary_table.name}_no_field_list'}):
         db.execute(f'COMMENT ON COLUMN {summary_table.name}.{row[0]} IS %(comment)s', {'comment': row[1]})
 
-    comment = (f'JSONB object of JSON paths in the {summary_table.data_field} object, excluding array indices. '
-               f'Keys in the object are the paths and values are NULL. '
+    comment = (f'All JSON paths in the {summary_table.data_field} object, excluding array indices, expressed as '
+               f'a JSONB object in which keys are paths and values are NULL. '
                f'This column is only available if the --field-lists option was used.')
     db.execute(f'COMMENT ON COLUMN {summary_table.name}.field_list IS %(comment)s', {'comment': comment})
 

tests/test_add.py

@@ -202,7 +202,7 @@ def test_command(db, tables_only, tables, views, caplog):
 
         # Check count of keys in field_list field for lowest ids in each summary table.
         each_table = '''
-            (SELECT
+            SELECT
                 count(*)
             FROM
                 (SELECT
@@ -216,7 +216,6 @@ def test_command(db, tables_only, tables, views, caplog):
                        {}
                     LIMIT 1) AS field_list
                 ) AS each
-            )
         '''
 
         union_all = ' UNION ALL '.join(each_table.format(table.name, table.primary_keys) for table in SUMMARY_TABLES)