edited comments for headers.rst

docs/headers.rst

@@ -1,7 +1,7 @@
 
 gemmi/addends.hpp
     Addends to scattering form factors used in DensityCalculator
-    and in StructureFactorCalculator.
+    and StructureFactorCalculator.
 
 gemmi/align.hpp
     Sequence alignment, label_seq_id assignment, structure superposition.
@@ -18,11 +18,11 @@ gemmi/asumask.hpp
     AsuBrick and MaskedGrid that is used primarily as direct-space asu mask.
 
 gemmi/atof.hpp
-    Functions that convert string to floating-point number ignoring locale.
+    Functions that convert strings to floating-point numbers ignoring locale.
     Simple wrappers around fastfloat::from_chars().
 
 gemmi/atox.hpp
-    Locale-independent functions that convert string to integer,
+    Locale-independent functions that convert strings to integers,
     equivalents of standard isspace and isdigit, and a few helper functions.
 
 gemmi/bessel.hpp
@@ -46,6 +46,7 @@ gemmi/calculate.hpp
 
 gemmi/ccp4.hpp
     CCP4 format for maps and masks.
+    See also read_map.hpp.
 
 gemmi/cellred.hpp
     Unit cell reductions: Buerger, Niggli, Selling-Delaunay.
@@ -57,13 +58,14 @@ gemmi/chemcomp.hpp
 gemmi/cif.hpp
     CIF parser (based on PEGTL) with pluggable actions,
     and a set of actions that prepare Document.
+    To just read the CIF format, include read_cif.hpp instead.
 
 gemmi/cif2mtz.hpp
     A class for converting SF-mmCIF to MTZ (merged or unmerged).
 
 gemmi/cifdoc.hpp
-    struct Document that represents the CIF file (but can be also
-    read from JSON file, such as CIF-JSON or mmJSON).
+    struct Document that represents the CIF file (but can also be
+    read from a different representation, such as CIF-JSON or mmJSON).
 
 gemmi/contact.hpp
     Contact search, based on NeighborSearch from neighbor.hpp.
@@ -78,9 +80,9 @@ gemmi/dencalc.hpp
     Tools to prepare a grid with values of electron density of a model.
 
 gemmi/dirwalk.hpp
-    Classes for iterating files in a directory tree, top-down,
-    in an alphabetical order.  It wraps the tinydir library (as we cannot
-    depend on C++17 <filesystem> yet).
+    Classes for iterating over files in a directory tree, top-down,
+    in alphabetical order. Wraps the tinydir library (as we cannot yet
+    depend on C++17 <filesystem>).
 
 gemmi/ecalc.hpp
     Normalization of amplitudes F->E ("Karle" approach, similar to CCP4 ECALC).
@@ -107,7 +109,7 @@ gemmi/floodfill.hpp
 
 gemmi/formfact.hpp
     Calculation of atomic form factors approximated by a sum of Gaussians.
-    Tables with numeric coefficient are in it92.hpp and c4322.hpp.
+    Tables with numerical coefficients are in it92.hpp and c4322.hpp.
 
 gemmi/fourier.hpp
     Fourier transform applied to map coefficients.
@@ -127,7 +129,7 @@ gemmi/gz.hpp
 
 gemmi/input.hpp
     Input abstraction.
-    Used to decouple file reading and uncompression.
+    Used to decouple file reading and decompression.
 
 gemmi/intensit.hpp
     Class Intensities that reads multi-record data from MTZ, mmCIF or XDS_ASCII
@@ -161,32 +163,30 @@ gemmi/metadata.hpp
     Metadata from coordinate files.
 
 gemmi/mmcif.hpp
-    Read mmcif (PDBx/mmCIF) file into a Structure from model.hpp.
+    Read mmCIF (PDBx/mmCIF) file into a Structure from model.hpp.
 
 gemmi/mmcif_impl.hpp
-    Function used in both mmcif.hpp and refln.hpp (for coordinate and
+    Functions used in both mmcif.hpp and refln.hpp (for coordinate and
     reflection mmCIF files).
 
 gemmi/mmdb.hpp
     Converts between gemmi::Structure and mmdb::Manager.
 
 gemmi/mmread.hpp
-    Read any supported coordinate file.
+    Read any supported coordinate file. Usually, mmread_gz.hpp is preferred.
 
 gemmi/mmread_gz.hpp
     Functions for reading possibly gzipped coordinate files.
-    Trivial wrappers that can make compilation faster
-    by having a separate implementation file src/mmread_gz.cpp.
 
 gemmi/model.hpp
-    Data structures to keep macromolecular structure model.
+    Data structures to store macromolecular structure models.
 
 gemmi/modify.hpp
     Modify various properties of the model.
 
 gemmi/monlib.hpp
     Monomer library - (Refmac) restraints dictionary,
-    which is made of monomers (chemical components), links and modifications.
+    which consists of monomers (chemical components), links, and modifications.
 
 gemmi/mtz.hpp
     MTZ reflection file format.
@@ -203,32 +203,29 @@ gemmi/neutron92.hpp
     from Neutron News, Vol. 3, No. 3, 1992.
 
 gemmi/numb.hpp
-    Utilities for parsing CIF numbers (the CIF spec calls it 'numb').
+    Utilities for parsing CIF numbers (the CIF spec calls them 'numb').
 
 gemmi/pdb.hpp
-    Read PDB file format and store it in Structure.
+    Read the PDB file format and store it in Structure.
 
 gemmi/pdb_id.hpp
-    handling PDB ID and $PDB_DIR: is_pdb_code(), expand_pdb_code_to_path()
+    Handling PDB ID and $PDB_DIR: is_pdb_code(), expand_pdb_code_to_path(), ...
 
 gemmi/pirfasta.hpp
-    Read sequence from PIR or (multi-)FASTA format.
+    Read sequences from PIR or (multi-)FASTA formats.
 
 gemmi/polyheur.hpp
     Heuristic methods for working with chains and polymers.
-    Includes also a few well-defined functions, such as removal of waters.
+    Also includes a few well-defined functions, such as removal of waters.
 
 gemmi/qcp.hpp
     Structural superposition, the QCP method.
 
 gemmi/read_cif.hpp
     Functions for reading possibly gzipped CIF files.
-    Trivial wrappers that can make compilation faster
-    by having a separate implementation file src/read_cif.cpp.
 
 gemmi/read_map.hpp
     Functions for reading possibly gzipped CCP4 map files.
-    Trivial wrappers that can make compilation faster.
 
 gemmi/recgrid.hpp
     ReciprocalGrid -- grid for reciprocal space data.
@@ -246,7 +243,7 @@ gemmi/riding_h.hpp
     Place hydrogens according to bond lengths and angles from monomer library.
 
 gemmi/scaling.hpp
-    Anisotropic scaling of data (includes scaling of bulk solvent parameters)
+    Anisotropic scaling of data (includes scaling of bulk solvent parameters).
 
 gemmi/select.hpp
     Selections.
@@ -261,13 +258,13 @@ gemmi/seqtools.hpp
     Functions for working with sequences (other than alignment).
 
 gemmi/serialize.hpp
-    Binary serialization for Structure (as well as Model, UnitCell, etc)
+    Binary serialization for Structure (as well as Model, UnitCell, etc).
 
 gemmi/sfcalc.hpp
     Direct calculation of structure factors.
 
 gemmi/small.hpp
-    Representation of small molecule or inorganic crystal.
+    Representation of a small molecule or inorganic crystal.
     Flat list of atom sites. Minimal functionality.
 
 gemmi/smcif.hpp

include/gemmi/addends.hpp

@@ -1,7 +1,7 @@
 // Copyright 2020 Global Phasing Ltd.
 //
 // Addends to scattering form factors used in DensityCalculator
-// and in StructureFactorCalculator.
+// and StructureFactorCalculator.
 
 #ifndef GEMMI_ADDENDS_HPP_
 #define GEMMI_ADDENDS_HPP_

include/gemmi/atof.hpp

@@ -1,6 +1,6 @@
 // Copyright 2020 Global Phasing Ltd.
 //
-// Functions that convert string to floating-point number ignoring locale.
+// Functions that convert strings to floating-point numbers ignoring locale.
 // Simple wrappers around fastfloat::from_chars().
 
 #ifndef GEMMI_ATOF_HPP_

include/gemmi/atox.hpp

@@ -1,6 +1,6 @@
 // Copyright 2018 Global Phasing Ltd.
 //
-// Locale-independent functions that convert string to integer,
+// Locale-independent functions that convert strings to integers,
 // equivalents of standard isspace and isdigit, and a few helper functions.
 //
 // This file is named similarly to the standard functions atoi() and atof().

include/gemmi/ccp4.hpp

@@ -1,6 +1,7 @@
 // Copyright 2018 Global Phasing Ltd.
 //
 // CCP4 format for maps and masks.
+// See also read_map.hpp.
 
 #ifndef GEMMI_CCP4_HPP_
 #define GEMMI_CCP4_HPP_

include/gemmi/cif.hpp

@@ -2,6 +2,7 @@
 //
 // CIF parser (based on PEGTL) with pluggable actions,
 // and a set of actions that prepare Document.
+// To just read the CIF format, include read_cif.hpp instead.
 
 #ifndef GEMMI_CIF_HPP_
 #define GEMMI_CIF_HPP_

include/gemmi/cifdoc.hpp

@@ -1,7 +1,7 @@
 // Copyright 2017 Global Phasing Ltd.
 //
-// struct Document that represents the CIF file (but can be also
-// read from JSON file, such as CIF-JSON or mmJSON).
+// struct Document that represents the CIF file (but can also be
+// read from a different representation, such as CIF-JSON or mmJSON).
 
 #ifndef GEMMI_CIFDOC_HPP_
 #define GEMMI_CIFDOC_HPP_

include/gemmi/dirwalk.hpp

@@ -1,8 +1,8 @@
 // Copyright 2018 Global Phasing Ltd.
 //
-// Classes for iterating files in a directory tree, top-down,
-// in an alphabetical order.  It wraps the tinydir library (as we cannot
-// depend on C++17 <filesystem> yet).
+// Classes for iterating over files in a directory tree, top-down,
+// in alphabetical order. Wraps the tinydir library (as we cannot yet
+// depend on C++17 <filesystem>).
 
 // DirWalk<> iterates through all files and directories.
 // CifWalk yields only cif files (either files that end with .cif or .cif.gz,

include/gemmi/formfact.hpp

@@ -1,7 +1,7 @@
 // Copyright 2019 Global Phasing Ltd.
 
 // Calculation of atomic form factors approximated by a sum of Gaussians.
-// Tables with numeric coefficient are in it92.hpp and c4322.hpp.
+// Tables with numerical coefficients are in it92.hpp and c4322.hpp.
 
 #ifndef GEMMI_FORMFACT_HPP_
 #define GEMMI_FORMFACT_HPP_

include/gemmi/input.hpp

@@ -1,7 +1,7 @@
 // Copyright 2018 Global Phasing Ltd.
 //
 // Input abstraction.
-// Used to decouple file reading and uncompression.
+// Used to decouple file reading and decompression.
 
 #ifndef GEMMI_INPUT_HPP_
 #define GEMMI_INPUT_HPP_

include/gemmi/mmcif.hpp

@@ -1,6 +1,6 @@
 // Copyright 2017 Global Phasing Ltd.
 //
-// Read mmcif (PDBx/mmCIF) file into a Structure from model.hpp.
+// Read mmCIF (PDBx/mmCIF) file into a Structure from model.hpp.
 
 #ifndef GEMMI_MMCIF_HPP_
 #define GEMMI_MMCIF_HPP_

include/gemmi/mmcif_impl.hpp

@@ -1,6 +1,6 @@
 // Copyright 2019 Global Phasing Ltd.
 //
-// Function used in both mmcif.hpp and refln.hpp (for coordinate and
+// Functions used in both mmcif.hpp and refln.hpp (for coordinate and
 // reflection mmCIF files).
 
 #ifndef GEMMI_MMCIF_IMPL_HPP_

include/gemmi/mmread.hpp

@@ -1,6 +1,6 @@
 // Copyright 2017 Global Phasing Ltd.
 //
-// Read any supported coordinate file.
+// Read any supported coordinate file. Usually, mmread_gz.hpp is preferred.
 
 #ifndef GEMMI_MMREAD_HPP_
 #define GEMMI_MMREAD_HPP_

include/gemmi/mmread_gz.hpp

@@ -1,8 +1,6 @@
 // Copyright 2021 Global Phasing Ltd.
 //
 // Functions for reading possibly gzipped coordinate files.
-// Trivial wrappers that can make compilation faster
-// by having a separate implementation file src/mmread_gz.cpp.
 
 #ifndef GEMMI_MMREAD_GZ_HPP_
 #define GEMMI_MMREAD_GZ_HPP_

include/gemmi/model.hpp

@@ -1,6 +1,6 @@
 // Copyright 2017 Global Phasing Ltd.
 //
-// Data structures to keep macromolecular structure model.
+// Data structures to store macromolecular structure models.
 
 #ifndef GEMMI_MODEL_HPP_
 #define GEMMI_MODEL_HPP_

include/gemmi/monlib.hpp

@@ -1,7 +1,7 @@
 // Copyright 2018 Global Phasing Ltd.
 //
 // Monomer library - (Refmac) restraints dictionary,
-// which is made of monomers (chemical components), links and modifications.
+// which consists of monomers (chemical components), links, and modifications.
 
 #ifndef GEMMI_MONLIB_HPP_
 #define GEMMI_MONLIB_HPP_

include/gemmi/numb.hpp

@@ -1,6 +1,6 @@
 // Copyright 2017 Global Phasing Ltd.
 //
-// Utilities for parsing CIF numbers (the CIF spec calls it 'numb').
+// Utilities for parsing CIF numbers (the CIF spec calls them 'numb').
 //
 // Numb - the numeric type in CIF - is a number with optional
 // standard uncertainty (s.u.) in brackets: 1.23(8).

include/gemmi/pdb.hpp

@@ -1,6 +1,6 @@
 // Copyright 2017 Global Phasing Ltd.
 //
-// Read PDB file format and store it in Structure.
+// Read the PDB file format and store it in Structure.
 //
 // Based on the format spec:
 // https://www.wwpdb.org/documentation/file-format-content/format33/v3.3.html

include/gemmi/pdb_id.hpp

@@ -1,6 +1,6 @@
 // Copyright 2018 Global Phasing Ltd.
 //
-// handling PDB ID and $PDB_DIR: is_pdb_code(), expand_pdb_code_to_path()
+// Handling PDB ID and $PDB_DIR: is_pdb_code(), expand_pdb_code_to_path(), ...
 
 #ifndef GEMMI_PDB_ID_HPP_
 #define GEMMI_PDB_ID_HPP_

include/gemmi/pirfasta.hpp

@@ -1,6 +1,6 @@
 // Copyright 2020 Global Phasing Ltd.
 //
-// Read sequence from PIR or (multi-)FASTA format.
+// Read sequences from PIR or (multi-)FASTA formats.
 
 #ifndef GEMMI_PIRFASTA_HPP_
 #define GEMMI_PIRFASTA_HPP_

include/gemmi/polyheur.hpp

@@ -1,7 +1,7 @@
 // Copyright 2017-2018 Global Phasing Ltd.
 //
 // Heuristic methods for working with chains and polymers.
-// Includes also a few well-defined functions, such as removal of waters.
+// Also includes a few well-defined functions, such as removal of waters.
 
 #ifndef GEMMI_POLYHEUR_HPP_
 #define GEMMI_POLYHEUR_HPP_

include/gemmi/read_cif.hpp

@@ -1,8 +1,6 @@
 // Copyright 2021 Global Phasing Ltd.
 //
 // Functions for reading possibly gzipped CIF files.
-// Trivial wrappers that can make compilation faster
-// by having a separate implementation file src/read_cif.cpp.
 
 #ifndef GEMMI_READ_CIF_HPP_
 #define GEMMI_READ_CIF_HPP_

include/gemmi/read_map.hpp

@@ -1,7 +1,6 @@
 // Copyright 2021 Global Phasing Ltd.
 //
 // Functions for reading possibly gzipped CCP4 map files.
-// Trivial wrappers that can make compilation faster.
 
 #ifndef GEMMI_READ_MAP_HPP_
 #define GEMMI_READ_MAP_HPP_

include/gemmi/scaling.hpp

@@ -1,6 +1,6 @@
 // Copyright 2020 Global Phasing Ltd.
 //
-// Anisotropic scaling of data (includes scaling of bulk solvent parameters)
+// Anisotropic scaling of data (includes scaling of bulk solvent parameters).
 
 #ifndef GEMMI_SCALING_HPP_
 #define GEMMI_SCALING_HPP_

include/gemmi/serialize.hpp

@@ -1,6 +1,6 @@
 // Copyright Global Phasing Ltd.
 //
-// Binary serialization for Structure (as well as Model, UnitCell, etc)
+// Binary serialization for Structure (as well as Model, UnitCell, etc).
 //
 // Based on zpp::serializer, include third_party/serializer.h first.
 

include/gemmi/small.hpp

@@ -1,6 +1,6 @@
 // Copyright 2018 Global Phasing Ltd.
 //
-// Representation of small molecule or inorganic crystal.
+// Representation of a small molecule or inorganic crystal.
 // Flat list of atom sites. Minimal functionality.
 
 #ifndef GEMMI_SMALL_HPP_