Clean documentation (BlueBrain#248)

doc/Doxyfile

@@ -901,7 +901,7 @@ EXCLUDE_PATTERNS =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS = 
+EXCLUDE_SYMBOLS = *detail*
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -2051,7 +2051,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # C-preprocessor directives found in the sources and include files.
 # The default value is: YES.
 
-ENABLE_PREPROCESSING = YES
+ENABLE_PREPROCESSING = NO
 
 # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
 # in the source code. If set to NO, only conditional compilation will be

doc/mainpage.md

@@ -1,4 +1,16 @@
 HighFive documentation {#mainpage}
 ======================
 
-Welcome on HighFive documentation
+HighFive is a modern C++11 friendly interface for libhdf5.
+
+HighFive supports STL vector/string, eigen3, xtensor, Boost::UBLAS and Boost::Multi-array.
+
+It handles C++ from/to HDF5 automatic type mapping.
+
+HighFive does not require an additional library and supports both HDF5 thread safety and Parallel HDF5 (contrary to the official hdf5 cpp).
+
+HighFive has two interfaces: normal HighFive and H5Easy.
+
+H5Easy is a high-level interface composed by two main functions: H5Easy::load and H5Easy::dump.
+
+HighFive is a wrapper of HDF5 library which take care of ownership of your HDF5 objects.

include/highfive/H5Easy.hpp

@@ -48,43 +48,40 @@ using HighFive::Exception;
 using HighFive::File;
 
 ///
-/// Write mode for DataSets
-///
+/// \brief Write mode for DataSets
 enum class DumpMode
 {
- Create,
- Overwrite
+ Create, /*!< Dump only if DataSet does not exist, otherwise throw. */
+ Overwrite /*!< If DataSet already exists overwrite it if data has the same shape, otherwise throw. */
 };
 
 ///
 /// \brief Get the size of an existing DataSet in an open HDF5 file.
 ///
-/// \param file opened File
-/// \param path path of the DataSet
+/// \param file A readable opened file
+/// \param path Path of the DataSet
 ///
-/// \return size the size of the DataSet
+/// \return Size of the DataSet
 inline size_t getSize(const File& file, const std::string& path);
 
 ///
-/// \brief Get the shape of an existing DataSet in an open HDF5 file.
+/// \brief Get the shape of an existing DataSet in an readable file.
 ///
-/// \param file opened File
-/// \param path path of the DataSet
+/// \param file A readable opened file
+/// \param path Path of the DataSet
 ///
 /// \return the shape of the DataSet
 inline std::vector<size_t> getShape(const File& file, const std::string& path);
 
 ///
-/// \brief Write "Eigen::Matrix<T,Rows,Cols,Options>" to a new DataSet
-/// in an open HDF5 file.
+/// \brief Write an Eigen matrix to a new DataSet in an open HDF5 file.
 ///
-/// \param file opened File (has to be writeable)
-/// \param path path of the DataSet
-/// \param data the data to write
-/// \param mode write mode (DumpMode::Create | DumpMode::Overwrite)
+/// \param file Writeable opened file
+/// \param path Path of the DataSet
+/// \param data eigen matrix to write
+/// \param mode Write mode
 ///
-/// \return dataset the newly created DataSet (e.g. to add an
-/// attribute)
+/// \return the newly created DataSet
 ///
 #ifdef H5_USE_EIGEN
 template <class T, int Rows, int Cols, int Options, int MaxRows, int MaxCols>
@@ -97,13 +94,12 @@ inline DataSet dump(File& file,
 ///
 /// \brief Write "xt::xarray<T>" to a new DataSet in an open HDF5 file.
 ///
-/// \param file opened File (has to be writeable)
-/// \param path path of the DataSet
-/// \param data the data to write
-/// \param mode write mode (DumpMode::Create | DumpMode::Overwrite)
+/// \param file A writeable opened HDF5 file
+/// \param path Path of the DataSet
+/// \param data xtensor array to write
+/// \param mode write mode
 ///
-/// \return dataset the newly created DataSet (e.g. to add an
-/// attribute)
+/// \return the newly created DataSet
 ///
 #ifdef H5_USE_XTENSOR
 template <class T>
@@ -119,10 +115,9 @@ inline DataSet dump(File& file,
 /// \param file opened File (has to be writeable)
 /// \param path path of the DataSet
 /// \param data the data to write
-/// \param mode write mode (DumpMode::Create | DumpMode::Overwrite)
+/// \param mode write mode
 ///
-/// \return dataset the newly created DataSet (e.g. to add an
-/// attribute)
+/// \return the newly created DataSet
 ///
 #ifdef H5_USE_XTENSOR
 template <class T, size_t rank>
@@ -138,10 +133,9 @@ inline DataSet dump(File& file,
 /// \param file opened File (has to be writeable)
 /// \param path path of the DataSet
 /// \param data the data to write
-/// \param mode write mode (DumpMode::Create | DumpMode::Overwrite)
+/// \param mode write mode
 ///
-/// \return dataset the newly created DataSet (e.g. to add an
-/// attribute)
+/// \return the newly created DataSet
 ///
 template <class T>
 inline DataSet dump(File& file,
@@ -152,13 +146,12 @@ inline DataSet dump(File& file,
 ///
 /// \brief Write scalar/string to a new DataSet in an open HDF5 file.
 ///
-/// \param file opened File (has to be writeable)
-/// \param path path of the DataSet
-/// \param data the data to write
-/// \param mode write mode (DumpMode::Create | DumpMode::Overwrite)
+/// \param file Writeable opened file
+/// \param path Path of the DataSet
+/// \param data Data to write
+/// \param mode Write mode
 ///
-/// \return dataset the newly created DataSet (e.g. to add an
-/// attribute)
+/// \return The newly created DataSet
 ///
 template <class T>
 inline DataSet dump(File& file,
@@ -174,8 +167,7 @@ inline DataSet dump(File& file,
 /// \param data the data to write
 /// \param idx the indices to which to write
 ///
-/// \return dataset the (newly created) DataSet (e.g. to add an
-/// attribute)
+/// \return The newly created DataSet
 ///
 template <class T>
 inline DataSet dump(File& file,
@@ -190,7 +182,7 @@ inline DataSet dump(File& file,
 /// \param idx the indices to load
 /// \param path path of the DataSet
 ///
-/// \return data the read data
+/// \return the read data
 ///
 template <class T>
 inline T load(const File& file,
@@ -203,7 +195,7 @@ inline T load(const File& file,
 /// \param file opened File (has to be writeable)
 /// \param path path of the DataSet
 ///
-/// \return data the read data
+/// \return the read data
 ///
 template <class T>
 inline T load(const File& file, const std::string& path);