diff --git a/CMakeLists.txt b/CMakeLists.txt
index e359dab6e4e4cb669df99df37fe0638da53b8613..f5e1e39ad76144e87b6a31edc06654005760b7c8 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -47,6 +47,11 @@ if (DOXYGEN_FOUND)
set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/doc/librelaxisloader.doxygen.in)
set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/doc/librelaxisloader.doxygen)
configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+
+ set(README_IN ${CMAKE_CURRENT_SOURCE_DIR}/doc/readme.md.in)
+ set(README_OUT ${CMAKE_CURRENT_BINARY_DIR}/doc/readme.md)
+ configure_file(${README_IN} ${README_OUT} @ONLY)
+
message("Doxygen build started")
add_custom_target(doc
diff --git a/README.md b/README.md
index 05833adcac767254dd73b64286887b7364085d86..bd0b1ea7e21b870cab23080a5a5231329b187201 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,3 @@
-[comment]: \page README Readme
-
# librelaxisloader
librelaxisloader is a shared library that allows you to load data from RelaxIS3 files. This library supports only files with a DatabaseFormat of "1"
diff --git a/doc/librelaxisloader.doxygen.in b/doc/librelaxisloader.doxygen.in
index 04a9184d75e5e30ba22f894deb10eee84b9d92f2..b1cd655ebec5a2723c25922af326f75bab576e68 100644
--- a/doc/librelaxisloader.doxygen.in
+++ b/doc/librelaxisloader.doxygen.in
@@ -864,7 +864,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = @CMAKE_CURRENT_SOURCE_DIR@/relaxisloader @CMAKE_CURRENT_SOURCE_DIR@/doc/mainpage.txt @CMAKE_CURRENT_SOURCE_DIR@/README.md
+INPUT = @CMAKE_CURRENT_SOURCE_DIR@/relaxisloader @CMAKE_CURRENT_SOURCE_DIR@/doc/mainpage.txt @CMAKE_CURRENT_BINARY_DIR@/doc/readme.md
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
diff --git a/doc/readme.md.in b/doc/readme.md.in
new file mode 100644
index 0000000000000000000000000000000000000000..2da6f9406eef0df392e800082dfa892f42880bf1
--- /dev/null
+++ b/doc/readme.md.in
@@ -0,0 +1,3 @@
+\page README Readme
+
+\include{doc} @CMAKE_CURRENT_SOURCE_DIR@/README.md
diff --git a/relaxisloader/relaxisloader.h b/relaxisloader/relaxisloader.h
index 4a7a7bb3a605a9b96ac93eb4d992b0fcedbed056..298e3a74f3a25544f1adeeda53186a97dc260f8d 100644
--- a/relaxisloader/relaxisloader.h
+++ b/relaxisloader/relaxisloader.h
@@ -33,6 +33,9 @@ API for use by librelaxisloader users.
struct rxfile;
+/**
+ * @brief This struct represents a RelaxIS "project" containing any number of spectra.
+ **/
struct rlx_project {
int id; /**< Project id*/
char* name; /**< Name of the project */
@@ -40,29 +43,40 @@ struct rlx_project {
};
/**
- * @brief Frees a project struct
+ * @brief This frees a project struct.
*
- * @param proj project struct to be freed, or NULL
+ * This function must always be used for every singular rlx_project struct to avoid memory leaks.
+ * It is safe to pass NULL to this function.
+ *
+ * @param proj the Project struct to be freed, or NULL.
*/
void rlx_project_free(struct rlx_project* proj);
/**
- * @brief Frees an array of project structs
+ * @brief This frees an array of project structs.
+ *
+ * This function must always be used for array of rlx_project structs to avoid memory leaks.
*
- * @param proj_array array of project structs to be freed
+ * @param proj_array The Array of project structs to be freed.
*/
void rlx_project_free_array(struct rlx_project** proj_array);
+/**
+ * @brief This struct is used to house a single impedance data point.
+ **/
struct rlx_datapoint {
- double im; /**< imaginary part of the measurement in Ohms*/
- double re; /**< real part of the measurement in Ohms*/
- double omega; /**< frequency of the measurement in rad/s*/
+ double im; /**< Imaginary part of the measurement in Ohms*/
+ double re; /**< Real part of the measurement in Ohms*/
+ double omega; /**< Frequency of the measurement in rad/s*/
};
+/**
+ * @brief This struct is used to house an EIS spectra and associated meta-data.
+ **/
struct rlx_spectra {
- int id; /**< Spectra id, also called "file" in relaxis*/
+ int id; /**< Spectra id, also called "file" in RelaxIS*/
- struct rlx_datapoint* datapoints; /**< data points of the spectrum*/
+ struct rlx_datapoint* datapoints; /**< Data points of the spectrum*/
size_t length; /**< Amount of data points in the spectrum*/
char* circuit; /**< RelaxIS circuit description string*/
@@ -70,21 +84,26 @@ struct rlx_spectra {
int project_id; /**< Id of the project this spectrum belongs to*/
double freq_lower_limit; /**< Lower limit of frequency range of this spectrum*/
double freq_upper_limit; /**< Upper limit of frequency range of this spectrum*/
- time_t date_added;
- time_t date_fitted;
+ time_t date_added; /**< UNIX time the spectra was added. Unfortionatly, due to a deficiency in RelaxIS, the timezone of this time is unkown and the time specified assumes the project was created in a GMT+0 timezone.*/
+ time_t date_fitted; /**< UNIX time the spectra was last fitted. Only valid if fitted is true. Unfortionatly, due to a deficiency in RelaxIS, the timezone of this time is unkown and the time specified assumes the project was last fitted in a GMT+0 timezone.*/
};
/**
- * @brief Frees a spectra struct
+ * @brief This frees a spectra struct.
+ *
+ * This function must always be used for every singular rlx_spectra struct to avoid memory leaks.
+ * It is safe to pass NULL to this function.
*
- * @param spectra spectra to be freed
+ * @param spectra The spectra to be freed.
*/
void rlx_spectra_free(struct rlx_spectra* spectra);
/**
* @brief Frees an array of spectra structs
*
- * @param spectra_array array of spectra structs to be freed
+ * This function must always be used for every array of rlx_spectra structs to avoid memory leaks.
+ *
+ * @param spectra_array The array of spectra structs to be freed.
*/
void rlx_spectra_free_array(struct rlx_spectra** spectra_array);
@@ -115,7 +134,7 @@ void rlx_fitparam_free_array(struct rlx_fitparam** param_array);
/**
* @brief Frees a project struct
*
- * @param path the filesystem path where the file shall be opened
+ * @param path the file system path where the file shall be opened
* @param error if an error occurs and NULL is returned, pointer to an error string is set here,
* owned by librelaxisloader, do not free, valid only until next call to librelaxisloader
* @return a rxfile struct or NULL if opening was unsuccessful, to be closed with rlx_close_file
@@ -127,6 +146,8 @@ void rlx_close_file(struct rxfile* file);
/**
* @brief Gets all the projects in a given RelaxIS file
*
+ * If this function encounters an error it will return NULL and set an error at rlx_get_errnum.
+ *
* @param file file to load projects from
* @param length pointer to a size_t where the number of projects will be stored, or NULL
* @return A NULL terminated array of project structs will be allocated here, to be freed with rlx_project_free_array, or NULL on error
@@ -136,6 +157,8 @@ struct rlx_project** rlx_get_projects(struct rxfile* file, size_t* length);
/**
* @brief Loads all spectra from file in given project
*
+ * If this function encounters an error it will return NULL and set an error at rlx_get_errnum.
+ *
* @param file file to load spectra from
* @param project project to load spectra from
* @return A NULL terminated array of spectra structs will be allocated here, to be freed with rlx_spectra_free_array, or NULL on error
@@ -145,6 +168,8 @@ struct rlx_spectra** rlx_get_all_spectra(struct rxfile* file, const struct rlx_p
/**
* @brief Loads spectra ids that are associated with a given project
*
+ * If this function encounters an error it will return NULL and set an error at rlx_get_errnum.
+ *
* @param file file to load spectra from
* @param project project to load spectra from
* @param id spectra id for which to load parameters
@@ -156,6 +181,8 @@ int* rlx_get_spectra_ids(struct rxfile* file, const struct rlx_project* project,
/**
* @brief Loads spectra with a given spectra id and project from file
*
+ * If this function encounters an error it will return NULL and set an error at rlx_get_errnum.
+ *
* @param file file to load spectra from
* @param project project to load spectra from
* @param id spectra id to load
@@ -166,6 +193,8 @@ struct rlx_spectra* rlx_get_spectra(struct rxfile* file, const struct rlx_projec
/**
* @brief Loads the parameters for a given spectra id from file
*
+ * If this function encounters an error it will return NULL and set an error at rlx_get_errnum.
+ *
* @param file file to load spectra from
* @param project project to load spectra from
* @param id spectra id for which to load parameters
@@ -177,14 +206,14 @@ struct rlx_fitparam** rlx_get_fit_parameters(struct rxfile* file, const struct r
/**
* @brief Returns the last error returned on a file operation
*
- * @return relaxiloader error number
+ * @return relaxisloader error number
*/
int rlx_get_errnum(const struct rxfile* file);
/**
* @brief Returns a human readable error string for a given error number
*
- * @return Error string, owned by librelaxisloader do not free
+ * @return Error string, static lifetime, owned by librelaxisloader do not free
*/
const char* rlx_get_errnum_str(int errnum);