[minor] add comments

Author: dcherian

doc/io.rst

@@ -437,7 +437,7 @@ like ``'days'`` for ``timedelta64`` data. ``calendar`` should be one of the cale
 supported by netCDF4-python: 'standard', 'gregorian', 'proleptic_gregorian' 'noleap',
 '365_day', '360_day', 'julian', 'all_leap', '366_day'.
 
-By default, xarray uses the 'proleptic_gregorian' calendar and units of the smallest time
+By default, xarray uses the ``'proleptic_gregorian'`` calendar and units of the smallest time
 difference between values, with a reference time of the first time value.
 
 
@@ -448,9 +448,9 @@ Coordinates
 
 You can control the ``coordinates`` attribute written to disk by specifying ``DataArray.encoding["coordinates"]``.
 If not specified, xarray automatically sets ``DataArray.encoding["coordinates"]`` to a space-delimited list
-of names of coordinate variables that share dimensions with the variable.
+of names of coordinate variables that share dimensions with the ``DataArray`` being written.
 This allows perfect roundtripping of xarray datasets but may not be desirable.
-When an xarray dataset contains non-dimensional coordinates that do not share dimensions with any of
+When an xarray ``Dataset`` contains non-dimensional coordinates that do not share dimensions with any of
 the variables, these coordinate variable names are saved under a "global" ``"coordinates"`` attribute.
 This is not CF-compliant but again facilitates roundtripping of xarray datasets.
 

xarray/conventions.py

@@ -662,6 +662,8 @@ def _encode_coordinates(variables, attributes, non_dim_coord_names):
                 variable_coordinates[k].add(coord_name)
 
     variables = {k: v.copy(deep=False) for k, v in variables.items()}
+
+    # keep track of variable names written to file under the "coordinates" attributes
     written_coords = set()
     for name, var in variables.items():
         encoding = var.encoding
@@ -676,14 +678,13 @@ def _encode_coordinates(variables, attributes, non_dim_coord_names):
         if "coordinates" in attrs:
             written_coords.update(attrs["coordinates"].split())
 
-    global_coordinates.difference_update(written_coords)
-
     # These coordinates are not associated with any particular variables, so we
     # save them under a global 'coordinates' attribute so xarray can roundtrip
     # the dataset faithfully. Because this serialization goes beyond CF
     # conventions, only do it if necessary.
     # Reference discussion:
     # http://mailman.cgd.ucar.edu/pipermail/cf-metadata/2014/007571.html
+    global_coordinates.difference_update(written_coords)
     if global_coordinates:
         attributes = dict(attributes)
         if "coordinates" in attributes: