From 3ca76032c8b4b57c4e27e1067622745bb06ccd7a Mon Sep 17 00:00:00 2001
From: Ryan Curtin <ryan@ratml.org>
Date: Thu, 3 Sep 2020 12:07:14 -0400
Subject: [PATCH] Update documentation.

---
 src/mlpack/core/data/load.hpp | 28 +++++++++++++++-------------
 src/mlpack/core/data/save.hpp | 18 ++++++++++++------
 2 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/src/mlpack/core/data/load.hpp b/src/mlpack/core/data/load.hpp
index 50184e594d..d5da43a1ff 100644
--- a/src/mlpack/core/data/load.hpp
+++ b/src/mlpack/core/data/load.hpp
@@ -28,23 +28,25 @@ namespace data /** Functions to load and save matrices and models. */ {
 /**
  * Loads a matrix from file, guessing the filetype from the extension.  This
  * will transpose the matrix at load time (unless the transpose parameter is set
- * to false).  If the filetype cannot be determined, an error will be given.
+ * to false).
  *
  * The supported types of files are the same as found in Armadillo:
  *
- *  - CSV (csv_ascii), denoted by .csv, or optionally .txt
- *  - TSV (raw_ascii), denoted by .tsv, .csv, or .txt
- *  - ASCII (raw_ascii), denoted by .txt
- *  - Armadillo ASCII (arma_ascii), also denoted by .txt
- *  - PGM (pgm_binary), denoted by .pgm
- *  - PPM (ppm_binary), denoted by .ppm
- *  - Raw binary (raw_binary), denoted by .bin
- *  - Armadillo binary (arma_binary), denoted by .bin
- *  - HDF5, denoted by .hdf, .hdf5, .h5, or .he5
+ *  - CSV (arma::csv_ascii), denoted by .csv, or optionally .txt
+ *  - TSV (arma::raw_ascii), denoted by .tsv, .csv, or .txt
+ *  - ASCII (arma::raw_ascii), denoted by .txt
+ *  - Armadillo ASCII (arma::arma_ascii), also denoted by .txt
+ *  - PGM (arma::pgm_binary), denoted by .pgm
+ *  - PPM (arma::ppm_binary), denoted by .ppm
+ *  - Raw binary (arma::raw_binary), denoted by .bin
+ *  - Armadillo binary (arma::arma_binary), denoted by .bin
+ *  - HDF5 (arma::hdf5_binary), denoted by .hdf, .hdf5, .h5, or .he5
  *
- * If the file extension is not one of those types, an error will be given.
- * This is preferable to Armadillo's default behavior of loading an unknown
- * filetype as raw_binary, which can have very confusing effects.
+ * By default, this function will try to automatically determine the type of
+ * file to load based on its extension and by inspecting the file.  If you know
+ * the file type and want to specify it manually, override the default
+ * `inputLoadType` parameter with the correct type above (e.g.
+ * `arma::csv_ascii`.)
  *
  * If the parameter 'fatal' is set to true, a std::runtime_error exception will
  * be thrown if the matrix does not load successfully.  The parameter
diff --git a/src/mlpack/core/data/save.hpp b/src/mlpack/core/data/save.hpp
index f09473879a..49ddd51e1d 100644
--- a/src/mlpack/core/data/save.hpp
+++ b/src/mlpack/core/data/save.hpp
@@ -40,17 +40,23 @@ namespace data /** Functions to load and save matrices. */ {
  *  - Armadillo binary (arma_binary), denoted by .bin
  *  - HDF5 (hdf5_binary), denoted by .hdf5, .hdf, .h5, or .he5
  *
- * If the file extension is not one of those types, an error will be given.  If
- * the 'fatal' parameter is set to true, a std::runtime_error exception will be
- * thrown upon failure.  If the 'transpose' parameter is set to true, the matrix
- * will be transposed before saving.  Generally, because mlpack stores matrices
- * in a column-major format and most datasets are stored on disk as row-major,
- * this parameter should be left at its default value of 'true'.
+ * By default, this function will try to automatically determine the format to
+ * save with based only on the filename's extension.  If you would prefer to
+ * specify a file type manually, override the default
+ * `inputSaveType` parameter with the correct type above (e.g.
+ * `arma::csv_ascii`.)
+ *
+ * If the 'fatal' parameter is set to true, a std::runtime_error exception will
+ * be thrown upon failure.  If the 'transpose' parameter is set to true, the
+ * matrix will be transposed before saving.  Generally, because mlpack stores
+ * matrices in a column-major format and most datasets are stored on disk as
+ * row-major, this parameter should be left at its default value of 'true'.
  *
  * @param filename Name of file to save to.
  * @param matrix Matrix to save into file.
  * @param fatal If an error should be reported as fatal (default false).
  * @param transpose If true, transpose the matrix before saving (default true).
+ * @param inputSaveType File type to save to (defaults to arma::auto_detect).
  * @return Boolean value indicating success or failure of save.
  */
 template<typename eT>