From 65cd9ad6dc0fe1aed00f2c1ee81408f88eea9f14 Mon Sep 17 00:00:00 2001
From: Giovanni La Mura <giovanni.lamura@inaf.it>
Date: Fri, 13 Oct 2023 10:33:23 +0200
Subject: [PATCH] Add documentation to FORTRAN wrapper functions

---
 doc/src/config.dox    |  3 ++-
 src/include/file_io.h | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/doc/src/config.dox b/doc/src/config.dox
index d7006e0a..ee0f8baf 100644
--- a/doc/src/config.dox
+++ b/doc/src/config.dox
@@ -342,7 +342,7 @@ OPTIMIZE_OUTPUT_SLICE  = NO
 #
 # Note see also the list of default file extension mappings.
 
-EXTENSION_MAPPING      =
+EXTENSION_MAPPING      = f=FortranFixed f90=FortranFree
 
 # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 # according to the Markdown format, which allows for more readable
@@ -984,6 +984,7 @@ INPUT_FILE_ENCODING    =
 # *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice.
 
 FILE_PATTERNS          = *.cpp \
+		         *.f \
 		         *.h \
 			 *.md
 
diff --git a/src/include/file_io.h b/src/include/file_io.h
index 2c6fdd1d..2ae3a28a 100644
--- a/src/include/file_io.h
+++ b/src/include/file_io.h
@@ -1,6 +1,43 @@
+/*! \file file_io.h
+ *
+ * C++ wrapper of FORTRAN I/O operations with files.
+ */
+
+/*! \brief Open a file for subsequent access.
+ *
+ * \param uid: `int*` Pointer to the unit ID to be associated to the file.
+ * \param name: `char*` C-string for file name (max. length of 63).
+ * \param sta: `char*` C-string for file status (max. length of 7).
+ * \param mode: `char*` C-string for access mode (max. length of 11).
+ */
 extern "C" void open_file_(int*, const char*, const char*, const char*);
+/*! \brief Close a previously opened file.
+ *
+ * \param uid: `int*` Pointer to the unit ID of the file.
+ */
 extern "C" void close_file_(int*);
+/*! \brief Read an integer value from a file.
+ *
+ * \param uid: `int*` Pointer to the unit ID of the file.
+ * \param value: `int*` Pointer of the variable to be updated.
+ */
 extern "C" void read_int_(int*, int*);
+/*! \brief Write a complex value to a file.
+ *
+ * \param uid: `int*` Pointer to the unit ID of the file.
+ * \param real: `double*` Pointer to the real part of the value.
+ * \param imag: `double*` Pointer to the imaginary part of the value.
+ */
 extern "C" void write_complex_(int*, double*, double*);
+/*! \brief Write a double precision float value to a file.
+ *
+ * \param uid: `int*` Pointer to the unit ID of the file.
+ * \param value: `double*` Pointer to the variable to be written.
+ */
 extern "C" void write_double_(int*, double*);
+/*! \brief Write an integer value to a file.
+ *
+ * \param uid: `int*` Pointer to the unit ID of the file.
+ * \param value: `int*` Pointer to the variable to be written.
+ */
 extern "C" void write_int_(int*, int*);
-- 
GitLab