Examples in docstring, changelog

Author: Andrew Yang

CHANGELOG.md

@@ -1,20 +1,32 @@
 # Release notes
 
-## Version 3.1.0 – 2022-12-09
+## Version 3.2.0 – 2023-8-**
 
 ### Added
 
-- Compatibility with Python 3.10, 3.9, 3.8
+- CI Coverage.
+- New tests for loadData function.
 
 ### Changed
 
-### Deprecated
+- loadData function now toggleable. Can return either (a) data read from data blocks or (b) header
+information stored above the data block.
+- Exclude wx from tests.
 
 ### Removed
 
-- Remove the support for Python 3.5, 3.6.
+- Remove use of pkg_resources (deprecated).
+- No longer use Travis.
 
-### Fixed
+## Version 3.1.0 – 2022-12-09
+
+### Added
+
+- Compatibility with Python 3.10, 3.9, 3.8
+
+### Removed
+
+- Remove the support for Python 3.5, 3.6.
 
 ## Version 3.0.0 -- 2019-03-12
 

src/diffpy/utils/parsers/loaddata.py

@@ -19,22 +19,30 @@
 def loadData(filename, minrows=10, headers=False, hdel='=', hignore=None, **kwargs):
     """Find and load data from a text file.
 
-    The data reading starts at the first matrix block of at least minrows rows
-    and constant number of columns.  This seems to work for most of the
-    datafiles including those generated by PDFGetX2.
+    The data block is identified as the first matrix block of at least minrows rows
+    and constant number of columns. This seems to work for most of the datafiles including
+    those generated by PDFGetX2.
 
     filename    -- name of the file we want to load data from.
     minrows     -- minimum number of rows in the first data block.
                    All rows must have the same number of floating point values.
-    headers     -- when true (default False), the function instead returns
-                   a dictionary of values specified in header.
+    headers     -- when False (defualt), the function returns a numpy array of the
+                   data in the data block. When True, the function instead returns a
+                   dictionary of parameters and their corresponding values parsed from
+                   header (information prior the data block). See hdel and hignore for
+                   options to help with parsing header information.
     hdel        -- (only used when headers enabled) delimiter for parsing header
-                   information.
+                   information (default '='). e.g. using default hdel, the line
+                   'parameter = p_value' is put into the dictionary as
+                   {parameter: p_value}.
     hignore     -- (only used when headers enabled) ignore header rows beginning
-                   with any elements in the hignore list
+                   with any elements in the hignore list. e.g. hignore=['# ', '[']
+                   means the following lines are skipped: '# qmax=10', '[defaults]'.
     kwargs      -- keyword arguments that are passed to numpy.loadtxt including
-                   the following arguments below.
-    delimiter   -- delimiter for the data in the block.
+                   the following arguments below. (See also numpy.loadtxt for more
+                   details.)
+    delimiter   -- delimiter for the data in the block (default None). e.g. for
+                   comma-separated values in the datablock, set delimiter to ','.
     usecols     -- zero-based index of columns to be loaded, by default use
                    all detected columns.  The reading skips data blocks that
                    do not have the usecols-specified columns.
@@ -43,9 +51,8 @@ def loadData(filename, minrows=10, headers=False, hdel='=', hignore=None, **kwar
                    Note transposing the loaded array as loadData(FILENAME).T
                    has the same effect.
 
-    Return a numpy array of the data. (See also numpy.loadtxt for more details.)
-    If headers enabled, instead returns a dictionary of values read from header
-    information.
+    Return a numpy array of the data. If headers enabled, instead returns a
+    dictionary of parameters read from the header.
     """
     from numpy import array, loadtxt
     # for storing header data