From 752f586c01960f550e92baf1016065264ef2823a Mon Sep 17 00:00:00 2001
From: Stephane Poirier <stephane-poirier@synchrotron-soleil.fr>
Date: Wed, 1 Feb 2023 11:37:48 +0100
Subject: [PATCH] Documentation update

---
 .gitignore                     |    1 +
 README                         |   29 +
 doc/Doxyfile                   |    2 +-
 include/nexuscpp/nexuscpp.h    |   45 +-
 include/nexuscpp/nxbuffer.h    |  317 +++++-----
 include/nexuscpp/nxfile.h      | 1035 ++++++++++++++++----------------
 include/nexuscpp/nxfinalizer.h |   74 ++-
 include/nexuscpp/nxwriter.h    |  449 +++++++++-----
 licence.txt                    |  165 +++++
 src/nxhdf5.cpp                 |    2 +-
 src/nxwriter.cpp               |    1 +
 11 files changed, 1288 insertions(+), 832 deletions(-)
 create mode 100644 README
 create mode 100644 licence.txt

diff --git a/.gitignore b/.gitignore
index 3e15e11..69f7c3e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 /.vscode/
+html/
 *.bin
 *.dll
 *.simu
diff --git a/README b/README
new file mode 100644
index 0000000..cefe5b0
--- /dev/null
+++ b/README
@@ -0,0 +1,29 @@
+------------------------------------------------------------------------------
+// NeXusCPP LIBRARY
+------------------------------------------------------------------------------
+
+ Copyright (C) 2005-2023 - S. Poirier, C. Rodrigez, J. Berthaud, N.Leclercq
+
+ NeXusCPP is a C++ NeXus files and datasets manipulation library
+ It is built on top of the HDF5 library.
+
+ The NeXusCPP library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License as published
+ by the Free Software Foundation; either version 2 of the License, or (at
+ your option) any later version.
+
+ The YAT4Tango library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+ Public License for more details.
+
+ A copy of the GPL version 3 is available below.
+
+ The reference documentation is available here : https://www2.synchrotron-soleil.fr/controle/docs/nexuscpp/nexuscpp_html/
+
+ Please read the ReleaseNotes.txt file to known about recent changes
+
+ Contact:
+      Stephane POIRIER (stephane.poirier@synchrotron-soleil.fr)
+      Synchrotron SOLEIL
+------------------------------------------------------------------------------
diff --git a/doc/Doxyfile b/doc/Doxyfile
index 594b20c..d59dcd6 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -38,7 +38,7 @@ PROJECT_NAME           = NexusCPP
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 3.2.2
+PROJECT_NUMBER         = 3.5.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
diff --git a/include/nexuscpp/nexuscpp.h b/include/nexuscpp/nexuscpp.h
index ae227d9..2be0586 100644
--- a/include/nexuscpp/nexuscpp.h
+++ b/include/nexuscpp/nexuscpp.h
@@ -1,16 +1,16 @@
 //*****************************************************************************
 /// Synchrotron SOLEIL
 ///
-/// NeXus C++ API over NAPI
+/// NeXus C++ API
 ///
-/// Creation : 2010/07/18
-/// Author   : Stephane Poirier
+/// Creation : 16/02/2005
+/// Authors  : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud
 ///
 /// This program is free software; you can redistribute it and/or modify it under
 /// the terms of the GNU General Public License as published by the Free Software
 /// Foundation; version 2 of the License.
-/// 
-/// This program is distributed in the hope that it will be useful, but WITHOUT 
+///
+/// This program is distributed in the hope that it will be useful, but WITHOUT
 /// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 /// FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 ///
@@ -19,6 +19,41 @@
 #ifndef __NX_CPP_H__
 #define __NX_CPP_H__
 
+// ----------------------------------------------------------------------------
+//! \mainpage NeXusCPP library
+//! \tableofcontents
+//! NeXusCPP is a C++ NeXus files and datasets library.\n
+//! It is built on top of the HDF5 library.\n
+//! Its purpose is to provide the developer with useful, easy to use and
+//! powerful C++ tools for creating/reading/writing NeXus files.\n
+//! The topics currently addressed by NeXusCPP library are:
+//!   - \subpage lowlevelPage "Low level API"
+//!   - \subpage highlevelPage "High level API"
+//!   - \subpage streamingPage "Streaming API"
+//!
+//! <b>Main Author & Maintainer:</b>\n
+//!   - Stephane Poirier - Synchrotron SOLEIL - France\n
+//!
+//! <b>NeXusCPP license:</b>
+//!
+//! Copyright (C) 2006-2021 The Tango Community (http://tango-controls.org)
+//!
+//! The NeXusCPP library is free software; you can redistribute it and/or modify it
+//! under the terms of the GNU General Public License as published by the Free
+//! Software Foundation; either version 2 of the License, or (at your option)
+//! any later version.
+//!
+//! The NeXusCPP library is distributed in the hope that it will be useful,
+//! but WITHOUT ANY WARRANTY; without even the implied warranty of
+//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+//! Public License for more details.
+//!
+//! See COPYING file for license details
+//!
+//! <b>Main Contact:</b>\n
+//!   Stephane Poirier - Synchrotron SOLEIL - France
+// ----------------------------------------------------------------------------
+
 // standard library objets
 #include <iostream>
 #include <vector>
diff --git a/include/nexuscpp/nxbuffer.h b/include/nexuscpp/nxbuffer.h
index b9bbb97..643987a 100644
--- a/include/nexuscpp/nxbuffer.h
+++ b/include/nexuscpp/nxbuffer.h
@@ -1,10 +1,10 @@
 //*****************************************************************************
 /// Synchrotron SOLEIL
 ///
-/// Nexus API for Tango servers
+/// Nexus C++ API
 ///
-/// Creation : 2011/01/12
-/// Authors  : Stephane Poirier, Clement Rodriguez
+/// Creation : 16/02/2005
+/// Authors  : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud
 ///
 /// This program is free software; you can redistribute it and/or modify it under
 /// the terms of the GNU General Public License as published by the Free Software
@@ -19,6 +19,23 @@
 #ifndef __NX_BUFFER_H__
 #define __NX_BUFFER_H__
 
+// ============================================================================
+//! \page streamingPage streaming NeXus API documentation
+//! \tableofcontents
+//!
+//! \section secC1 Streaming NeXus API
+//! The Streaming API provide an object classe that allow to write continuous
+//! data without knowing final datasets sizes and shapes
+//!
+//! \section secC2 Streaming NeXus API classes
+//! Links to classes : \n
+//!   - nxcpp::DataStreamer
+//!   - nxcpp::NexusDataStreamerFinalizer
+//!   - nxcpp::OverwriteError
+//!
+// ============================================================================
+
+
 // including standard files
 #ifndef __STRING_INCLUDED__
   #include <string>
@@ -93,10 +110,10 @@ private:
 */
 
 //=============================================================================
-/// OverwriteError
-///
-/// This class may be used by the DataStreamer in case of
-/// a buffer file already exists before the acquisition start
+//! OverwriteError
+//!
+//! This class may be used by the DataStreamer in case of
+//! a buffer file already exists before the acquisition start
 //=============================================================================
 class NEXUSCPP_DECL OverwriteError: public NexusException
 {
@@ -111,7 +128,7 @@ public:
 };
 
 //==============================================================================
-/// DataItemCategory
+//! DataItemCategory
 ///==============================================================================
 enum DataItemCategory
 {
@@ -128,33 +145,30 @@ enum DataItemCategory
 #define NX_ATTR_SLAB_STOP  "buf_stop"
 #define NX_ATTR_ACQ_BATCH  "buf_batch"
 
-/// type of buffered data
-/// '0' for one shoot data (scalar, spectrum or image), '1' for data subset in a 1D acquisition, ...
+// type of buffered data
+// '0' for one shoot data (scalar, spectrum or image), '1' for data subset in a 1D acquisition, ...
 #define NX_ATTR_DATA_DIM   "buf_dim"
 
 //==============================================================================
-/// Write notification
+//! Write notification
 //==============================================================================
 struct WriteNotification
 {
-  /// data item name
+  //! data item name
   std::string item_name;
 
-  /// The number of written items
+  //! The number of written items
   yat::uint32 write_count;
 
 };
 
-// Write notification callback
+//! Write notification callback
 YAT_DEFINE_CALLBACK(WriteNotificationCallback, WriteNotification);
 
 //==============================================================================
-/// DataStreamer
-///
-/// This class aims to ease the writing process of local NeXus files.
-///
-///@notice BufferedData is no longer instantiable because this class name
-///        is now deprecated
+//! DataStreamer
+//!
+//! This is a utility classe aimed to allow streaming data into NeXus files
 //==============================================================================
 class NEXUSCPP_DECL DataStreamer: public DatasetWriter::IFlushNotification,
                                   public NexusFileWriter::INotify,
@@ -163,12 +177,21 @@ class NEXUSCPP_DECL DataStreamer: public DatasetWriter::IFlushNotification,
 {
 public:
 
+  //! Memory mode
   typedef enum NEXUSCPP_DECL MemoryMode
   {
-    COPY = 0,  // Default mode for all data items
-    NO_COPY    // Applicable only for 2D data items (images)
+    //! Using COPY mode (default), data is internally copied so
+    //! input data buffer can be reused§deallocated immmadiately after pushing
+    //! data
+    COPY = 0,
+
+    //! NO_COPY allow faster streaming but you can't deallocate or reuse pushed
+    //! data buffer immediately, you have to be sure the data was properly written
+    //! (you can use a WriteNotificationCallBack in that purpose)
+    NO_COPY
   } MemoryMode;
 
+  //! Write statistices
   typedef struct NEXUSCPP_DECL Statistics
   {
     Statistics();
@@ -183,61 +206,63 @@ public:
     float       fAverageMbPerSec;
   } Statistics;
 
+  //! DataStreamer configuration structure
   typedef struct NEXUSCPP_DECL Config
   {
-    /// buffer file names suffix
+    //! buffer file names suffix
     yat::String buffer_name;
 
-    /// total number of data (may be either scalars, spectrums or images)
+    //! total number of data (may be either scalars, spectrums or images)
     std::size_t acquisition_size;
 
-    /// number of data to be stored into one buffer file
+    //! number of data to be stored into one buffer file
     std::size_t buffer_size;
 
-    /// Target directory for streamed data
+    //! Target directory for streamed data
     yat::String target_path;
 
-    /// Data source root name. data file will ba named using this name followed
-    /// by a index number
+    //! Data source root name. data file will ba named using this name followed
+    //! by a index number
     yat::String data_source;
 
-    /// The optional write notification callback
+    //! The optional write notification callback
     WriteNotificationCallback write_notif_cb;
 
-    /// SYNCHRONOUS OR ASYNCHRONOUS writing mode
+    //! SYNCHRONOUS OR ASYNCHRONOUS writing mode
     NexusFileWriter::WriteMode write_mode;
 
-    /// Compresssion filter options
+    //! Compresssion filter options
     FilterConfig filter_config;
 
-    /// Compression filer
+    //! Compression filer
     CompressionFilter compress_filter;
 
-    /// Minimum uncompressed byte size of data item that will be compressed
+    //! Minimum uncompressed byte size of data item that will be compressed
     std::size_t min_bytes_for_compression;
 
-    /// The data source device name
+    //! The data source device name
     yat::String device_name;
 
-    /// Messages logging handler
+    //! Messages logging handler
     IMessageHandler* message_handler_p;
 
-    /// Throw an exception if destination buffer file already exists ?
+    //! Throw an exception if destination buffer file already exists ?
     bool throw_if_file_exists;
 
     // ----------------
     // error management
     // ----------------
 
-    /// optional exception handler
+    //! optional exception handler
     IExceptionHandler* exception_handler_p;
 
-    /// max attempts on write access in case of error
+    //! max attempts on write access in case of error
     std::size_t max_attempts;
 
-    /// delay between each try in ms
+    //! delay between each try in ms
     std::size_t retry_delay;
 
+    //! c-tor
     Config()
     {
       acquisition_size = 0;
@@ -253,139 +278,161 @@ public:
     }
   } Config;
 
-  /// Constructor
+  //! Constructor
+  //!
+  //! \param cfg Configuration
   DataStreamer(const Config& cfg);
 
-  /// Destructors
+  //! Destructor
   virtual ~DataStreamer();
 
-  /// Initialization
-  /// @param config Config struct
+  // Initialization
+  //## Should be a private method...
   void Initialize(const Config& cfg);
 
-  /// Tell the streamer we start a new acquisition sequence, therefore the first file index of every stream
-  /// will be reset to '1'
-  /// This method whould not be called for all subsequent DataStreamer objects
-  ///
+  //! Tell the streamer we start a new acquisition sequence, therefore the first file index of every stream
+  //! will be reset to '1'
+  //! This method whould not be called for all subsequent DataStreamer objects
   static void ResetBufferIndex();
 
-  /// Set the write notification callback
-  /// Each tile a
-  ///
+  //! Set the write notification callback
+  //!
+  //! \param cb WritenotificationCallBack method
   void SetWriteNotificationCallback(const WriteNotificationCallback& cb);
 
   //@{  Data items declarations
 
-    /// Generic data item declaration
-    ///
+    //! Generic data item declaration
+    //!
+    //! Use this method to declare a new item for which you ha ve to stream data
+    //!
+    //! \param sItemName item name
+    //! \param viDimSize Dimensions array of the canonical data
+    //! \param bDataSignal If 'true' this item will ba marked as 'signal' in
+    //!  the Nexus files stream
     void AddDataItem(const std::string &sItemName, const std::vector<int>& viDimSize,
                      bool bDataSignal=true) ;
 
-    /// scalar data item
-    ///
+    //! Add a Scalar-type data item
+    //!
+    //! \param sItemName item name
+    //! \param bDataSignal If 'true' this item will ba marked as 'signal' in
     void AddDataItem0D(const std::string &sItemName, bool bDataSignal=true) ;
 
-    /// 1-d (spectrum) dataitem
-    ///
-    void AddDataItem1D(const std::string &sItemName, int iSizeDim, bool bDataSignal=true)
-                      ;
-
-    /// 2-d (image) dataitem
-    ///
+    //! Add a 1-D (spectrum) data item
+    //!
+    //! \param sItemName item name
+    //! \param iSizeDim size of the data item
+    //! \param bDataSignal If 'true' this item will ba marked as 'signal' in
+    void AddDataItem1D(const std::string &sItemName, int iSizeDim, bool bDataSignal=true);
+
+    //! Add a 2-D (image) data item
+    //!
+    //! \param sItemName item name
+    //! \param iSizeDim1 size of the 1st data item dimension
+    //! \param iSizeDim2 size of the 2nd data item dimension
+    //! \param bDataSignal If 'true' this item will ba marked as 'signal' in
     void AddDataItem2D(const std::string &sItemName, int iSizeDim1, int iSizeDim2,
                        bool bDataSignal=true) ;
 
-    /// axis data item (equals to 1-d data item but with additionnal attributes)
-    ///
+    //! Add a axis-type data item
+    //!
+    //! This type of data item is similar to 1-D data item but with additional
+    //! dataset attributes
+    //!
+    //! \param sItemName item name
+    //! \param iDimension related scan dimension for this axis (first is '1')
+    //! \param iOrder axis order on the dimension
     void AddDataAxis(const std::string &sItemName, int iDimension, int iOrder) ;
 
-    /// Set dataitem memory management mode
+    //! Set dataitem memory management mode
+    //!
+    //! \param sItemName item name
+    //! \param mode Writing mode (COPY/NO_COPY)
     void SetDataItemMemoryMode(const std::string &sItemName, MemoryMode mode);
 
   //@}
 
   //@{  Writing datas and attributes
-    /// PushData
-    ///
-    /// @param sItemName sensor's name to which data will be added
-    /// @param tData Added data
-    /// @param vtDetectPos sensor's data position in the acquisition multidimensional space
-    /// @param nCount canonical data count
-    ///
+    //! PushData
+    //!
+    //! \param sItemName sensor's name to which data will be added
+    //! \param tData Added data
+    //! \param nCount canonical data count
     template <class TYPE> void PushData(const std::string &sItemName, const TYPE *tData,
                                         unsigned int nCount=1);
 
-    /// PushAxisData
-    ///
-    /// @param sName Axis name on which datas will be added
-    /// @param viVecPos Axis value's position in the acquisition multidimensional space
-    /// @param pValue Measured position on the axis
-    ///
+    //! PushAxisData
+    //!
+    //! \param sName Axis name on which datas will be added
+    //! \param TValue Measured position on the axis
     template <class TYPE> void PushAxisData(const std::string &sName, TYPE TValue);
 
-    /// PushIntegerAttribute
-    /// Set an integer-type attribute belonging to the date item named sItemName.
-    ///
-    /// @param sItemName name of the dataitem or axis which the attribute will belong to
-    /// @param sName name of the attribute
-    /// @param lValue value of the attribute
+    //! PushIntegerAttribute
+    //! Set an integer-type attribute belonging to the date item named sItemName.
+    //!
+    //! \param sItemName name of the dataitem or axis which the attribute will belong to
+    //! \param sName name of the attribute
+    //! \param lValue value of the attribute
     ///
     void PushIntegerAttribute(const std::string &sItemName, const std::string &sName, long lValue);
 
-    /// PushFloatAttribute
-    /// Set an integer-type attribute belonging to the date item named sItemName.
-    ///
-    /// @param sItemName name of the dataitem or axis which the attribute will belong to
-    /// @param sName name of the attribute
-    /// @param lValue value of the attribute
-    ///
+    //! PushFloatAttribute
+    //! Set an integer-type attribute belonging to the date item named sItemName.
+    //!
+    //! \param sItemName name of the dataitem or axis which the attribute will belong to
+    //! \param sName name of the attribute
+    //! \param dValue value of the attribute
     void PushFloatAttribute(const std::string &sItemName, const std::string &sName, double dValue);
 
-    /// PushStringAttribute
-    /// Set an std::string-type attribute belonging to the date item named sItemName.
-    ///
-    /// @param sItemName name of the dataitem or axis which the attribute will belong to
-    /// @param sName name of the attribute
-    /// @param strValue value of the attribute
-    ///
+    //! PushStringAttribute
+    //! Set an std::string-type attribute belonging to the date item named sItemName.
+    //!
+    //! \param sItemName name of the dataitem or axis which the attribute will belong to
+    //! \param sName name of the attribute
+    //! \param strValue value of the attribute
     void PushStringAttribute(const std::string &sItemName, const std::string &sName,
                              const std::string &strValue) ;
 
   //@}
 
-  /// Set exception handler
-  ///
+  //! Set exception handler
+  //!
+  //! \param pHandler The exception handler
   void SetExceptionHandler(IExceptionHandler *pHandler);
 
-  /// Set message handler
-  ///
+  //! Set message handler
+  //!
+  //! \param pHandler The message handler
   void SetMessageHandler(IMessageHandler *pHandler);
 
-  /// Sets the name of the tango device
+  //! Sets the name of the tango device
+  //!
+  //§ \param strDevice Device name
   void SetDeviceName(const std::string &strDevice) { m_cfg.device_name = strDevice; }
 
-  ///  Reset buffer in order to start a new acquisition
+  //!  Reset buffer in order to start a new acquisition
   void Reset();
 
-  /// Terminate the buffering process
+  //! Terminate the buffering process
   void Finalize();
 
-  /// Abort the bufferization process
-  ///
-  /// @param bSynchronize if true wait for last pushed data to be recorder
-  ///
+  //! Abort the bufferization process
+  //!
+  //! \param bSynchronize if true wait for last pushed data to be recorder
   void Abort(bool bSynchronize=false);
 
-  /// Close the buffer and wait for synchronization
+  //! Close the buffer and wait for synchronization
   void Stop();
 
-  /// Ask if all data have been flushed
+  //! Ask if all data have been flushed
   bool IsDone();
 
-  /// Wait the recording of all pushed data
+  //! Wait the recording of all pushed data
   void Synchronize();
 
   //@{ Setters
+   //## deprecated methods
     void SetWriteMode(const NexusFileWriter::WriteMode &mode) { m_cfg.write_mode = mode; }
     void SetTargetFolder(const std::string &sPath) { m_cfg.target_path = sPath; }
   //@}
@@ -396,47 +443,43 @@ public:
     int  GetNbPushInFile() const { return m_cfg.buffer_size; }
   //@}
 
-  /// Clean
-  /// Clean all buffers from destination folder
-  /// @warning Don't use this method if you are in a multiple acquisition system
-  ///          (i.e: 1 acquisition for the whole system == n acquisition at device level)
-  ///
+  //! Clean
+  //! Clean all buffers from destination folder
+  //! \warning Don't use this method if you are in a multiple acquisition system
+  //!          (i.e: 1 acquisition for the whole system == n acquisition at device level)
   void Clean();
 
-  /// IFlushNotification
-  ///
+  //! IFlushNotification
   void OnFlushData(DatasetWriter* pWriter);
 
-  /// Check if a data item has been declared
-  ///
+  //! Check if a data item has been declared
   bool IsExistingItem(const std::string &sItemName);
 
-  // Exception handler
+  //! Get exception handler
   IExceptionHandler* ExceptionHandler() const{ return m_pExceptHandler; }
 
-  /// Message handler
+  //! Get message handler
   IMessageHandler* MessageHandler() const{ return m_pMsgHandler; }
 
   //@{ Statistics
 
-    /// Reset all statistics
+    //! Reset all statistics
     void ResetStatistics();
 
-    /// Gets a copy of the statistics
+    //! Gets a copy of the statistics
     Statistics GetStatistics() const;
 
   //@}
 
   //@{ Static methods
 
-    /// GenerateBufferName
-    /// Generate a standard buffer file's name according to the base
-    /// name and given indexes
-    ///
-    /// @param strPrefix prefix used to ensure uniqueness of file name
-    /// @param sBaseName buffer file base name
-    /// @param iIndex buffer file index
-    ///
+    //! GenerateBufferName
+    //! Generate a standard buffer file's name according to the base
+    //! name and given indexes
+    //!
+    //! \param sBaseName buffer file base name
+    //! \param lIndex buffer file index
+    //! \param strPrefix prefix used to ensure uniqueness of file name
     static std::string GenerateBufferName(const std::string &sBaseName, long lIndex,
                                           const std::string &strPrefix="");
 
@@ -500,16 +543,16 @@ private:
 
   // PrivPushData
   //
-  // @param sItemInfo sensor's information data
-  // @param tData Added data
-  // @param vtDetectPos sensor's data position in the acquisition multidimensional space
-  // @param nCount canonical data count
+  // sItemInfo sensor's information data
+  // tData Added data
+  // vtDetectPos sensor's data position in the acquisition multidimensional space
+  // nCount canonical data count
   //
   void PrivPushDataItems(DataItemInfo &sItemInfo, const void *pData, std::size_t nCount, bool bNoCopy);
 
   // Push pending data
   //
-  // @param sItemInfo sensor's information data
+  // sItemInfo sensor's information data
   //
   void PushPendingData(DataItemInfo& ItemInfo);
 
diff --git a/include/nexuscpp/nxfile.h b/include/nexuscpp/nxfile.h
index d97f739..c58e481 100644
--- a/include/nexuscpp/nxfile.h
+++ b/include/nexuscpp/nxfile.h
@@ -1,7 +1,7 @@
 //*****************************************************************************
 /// Synchrotron SOLEIL
 ///
-/// NeXus C++ API over NAPI
+/// NeXus C++ API
 ///
 /// Creation : 16/02/2005
 /// Author   : Stephane Poirier
@@ -19,6 +19,25 @@
 #ifndef __NX_FILE_H__
 #define __NX_FILE_H__
 
+// ============================================================================
+//! \page lowlevelPage NeXus API documentation
+//! \tableofcontents
+//!
+//! \section secA1 Low-level NeXus API classes
+//! The NeXus API implement generic classes in order to read and write NeXus data.
+//!
+//! \section secA2 NeXus API classes
+//! Links to NeXusAPI classes : \n
+//!   - nxcpp::NexusFile
+//!   - nxcpp::NexusDataSet
+//!   - nxcpp::NexusDataSetInfo
+//!   - nxcpp::NexusAttr
+//!   - nxcpp::NexusAttrInfo
+//!   - nxcpp::NexusItemInfo
+//!   - nxcpp::NexusItemID
+//!
+// ============================================================================
+
 // standard library objets
 #include <iostream>
 #include <vector>
@@ -62,17 +81,24 @@ const std::string g_strNoDataSet = "(no data set)";
 //=============================================================================
 enum FilterOption
 {
-  // Apply on ZLIB filter
+  //! Apply on ZLIB filter
   compression_level,
 
-  // BitShuffle filter
+  //! BitShuffle filter
   bitshuffle_compression, // default is BSHUF_H5_COMPRESS_LZ4
   bitshuffle_block_size
 };
 
-/// Filter options to be passed with CreateCompressedDataSet method
+//! Filter options to be passed with CreateCompressedDataSet method
 typedef std::map<FilterOption, int> FilterConfig;
 
+//! \brief List of known compression filters
+//!
+//! This enumerate all known filter but all filters are not
+//! necesseraly implemented. Check filter availability using the free functions
+//! IsCompressFilterAvailable & AvailableCompressFilters
+//! \see IsCompressFilterAvailable
+//! \see AvailableCompressFilters
 enum CompressionFilter
 {
   CompressNone,        // No compression
@@ -84,17 +110,18 @@ enum CompressionFilter
   CompressBzip2,       // bzip2     (not yet available)
 };
 
-/// Return 'true' if the given compression filter is currently available
+//! Return 'true' if the given compression filter is currently available
+//! \param filter_id filter identifier
 NEXUSCPP_DECL bool IsCompressFilterAvailable(CompressionFilter filter_id);
 
 /// Return the available compress filters
 NEXUSCPP_DECL std::set<CompressionFilter> AvailableCompressFilters();
 
 //=============================================================================
-/// NexusGlobalLock
-///
-/// Ensure exclusive access to the nexus file API during the scope of each instance
-/// of this class
+// NexusGlobalLock
+//
+// Ensure exclusive access to the nexus file API during the scope of each instance
+// of this class
 //=============================================================================
 class NexusGlobalLock
 {
@@ -106,7 +133,7 @@ public:
 // Forward declaration
 class NexusFileImpl;
 
-/// NeXus data types (see napi.h)
+// NeXus data types (see napi.h)
 enum NexusDataType
 {
   NX_NONE      = 0,  /// Value not defined in the NeXus API
@@ -122,21 +149,21 @@ enum NexusDataType
   NX_INT64     = 26,
   NX_UINT64    = 27,
   NX_BINARY    = 21,
-  /// Logical data types (not defined in NeXus API) readed in NeXus meta-DTD files
+  // Logical data types (not defined in NeXus API) readed in NeXus meta-DTD files
   ISO8601      = 100, /// (NX_CHAR)
   NX_INT       = 102, /// generic integer type
   NX_FLOAT     = 103  /// generic real type
 };
 
-/// NeXus return codes
+//! NeXus return codes
 enum NexusRC
 {
   NX_OK = 1,
   NX_EOD = -1,
-  NX_ITEM_NOT_FOUND = -2 /// Value not defined in the NeXus API
+  NX_ITEM_NOT_FOUND = -2 //! Value not defined in the NeXus API
 };
 
-/// Create access types
+// Create access types
 enum ENexusCreateMode
 {
   NX_HDF4 = 0,
@@ -144,12 +171,13 @@ enum ENexusCreateMode
   NX_XML       // Not implemented yet
 };
 
-const int MAX_RANK = 32;              // Max rank
+//! Max datasets rank
+const int MAX_RANK = 32;
 
 //=============================================================================
-/// NeXus exceptions
-///
-/// This class is designed to hold nexus exceptions
+//! NeXus exceptions
+//!
+//! This class is designed to hold nexus exceptions
 //=============================================================================
 class NEXUSCPP_DECL NexusException: public yat::Exception
 {
@@ -162,21 +190,20 @@ public:
   NexusException(const std::string& desc, const char *pcszOrigin):
     yat::Exception("NEXUSCPP_ERROR", desc.c_str(), pcszOrigin) {}
 
-  /// Prints error message on console
+  //! Prints error message on console
   void PrintMessage();
 
-  /// Copies error message in a pre-allocated std::string buffer
-  ///
-  /// @param pBuf Buffer (allocated by caller) to copy the message in
-  /// @param iLen Buffer length
-  ///
+  //! Copies error message in a pre-allocated std::string buffer
+  //!
+  //! \param pBuf Buffer (allocated by caller) to copy the message in
+  //! \param iLen Buffer length
   void GetMsg(char *pBuf, int iLen);
 };
 
 //=============================================================================
-/// NeXus item identifier
-///
-/// This class holds a nexus item ids
+//! NeXus item identifier
+//!
+//! This class holds a nexus item id
 //=============================================================================
 class NEXUSCPP_DECL NexusItemID
 {
@@ -191,9 +218,9 @@ public:
 };
 
 //=============================================================================
-/// NeXus Data set info
-///
-/// This class allow manipulation of NeXus Data sets and subsets
+//! NeXus Data set info
+//!
+//! This class allow manipulation of NeXus Data sets and subsets
 //=============================================================================
 class NEXUSCPP_DECL NexusDataSetInfo
 {
@@ -207,74 +234,67 @@ protected:
 
 public:
 
-  /// Returns size according to a data type
+  //! Returns size according to a data type
   static int DataTypeSize(NexusDataType eDataType);
 
-  /// Constructor
+  //! Constructor
   NexusDataSetInfo();
 
-  /// Destructor
+  //! Destructor
   ~NexusDataSetInfo();
 
-  /// Sets datas
-  ///
-  /// @param eDataType Data type
-  /// @param iRank Data rank
-  ///
+  //! Sets datas
+  //!
+  //! \param eDataType Data type
+  //! \param iRank Data rank
   void SetInfo(NexusDataType eDataType, int iRank);
 
-  /// Clears instance
+  //! Clears instance
   void Clear();
 
   //-----------------------------------------------------------------
-  /// @name Accessors
+  //! \name Accessors
   //@{
 
-  /// Returns the data type
+  //! Returns the data type
   NexusDataType DataType() const { return m_eDataType; }
 
-  /// Returns the data set rank
+  //! Returns the data set rank
   int Rank() const { return m_iRank; }
 
-  /// Returns the whole data set rank
+  //! Returns the whole data set rank
   int TotalRank() const { return m_iTotalRank; }
 
-  /// Returns size array of dimensions
-  ///
+  //! Returns size array of dimensions
   int *DimArray() const { return m_piDim; }
 
-  /// Returns size array of dimensions of the whole dataset
-  /// @note can be bigger than the storage array of this NexusDataSetInfo
-  ///
+  //! Returns size array of dimensions of the whole dataset
+  //! \remark can be bigger than the storage array of this NexusDataSetInfo
   int *TotalDimArray() const { return m_piTotalDim; }
 
-  /// Set the whole dataset dimension's sizes
-  ///
-  /// @param iRankSpace Rank of the whole dataset
-  /// @param piDimArray Dimension sizes of the whole dataset
-  ///
+  //! Set the whole dataset dimension's sizes
+  //!
+  //! \param iTotalRank Rank of the whole dataset
+  //! \param piTotalDim Dimension sizes of the whole dataset
   void SetTotalDim(int iTotalRank, int *piTotalDim);
 
-  /// Returns total size
-  ///
+  //! Returns total size
   int Size() const;
 
-  /// Returns 'true' if no data set info is stored
-  ///
+  //! Returns 'true' if no data set info is stored
   bool IsEmpty() const;
 
-  /// Returns datum size
-  ///
+  //! Returns datum size
   unsigned int DatumSize() const;
 
-  /// Returns buffer size
+  //! Returns buffer size
   unsigned int BufferSize() const { return Size() * DatumSize(); }
 
-  /// Returns array of indices of starting values in Ith dimension
-  ///
+  //! Returns array of indices of starting values in Ith dimension
   int *StartArray() const { return m_piStart; }
   int *StartArray();
 
+  //! Is the dataset info about a subset?
   bool IsSubset() const { return m_piStart ? true:false;}
 
   //@} Accessors
@@ -292,79 +312,79 @@ private:
   bool         m_owner;    // ownsership
 
 public:
-  /// Constructors
+  //! Default c-tor
   NexusDataSet();
+
+  //! Copy c-tor
   NexusDataSet(const NexusDataSet &dataset);
+
+  //! c-tor
+  //!
+  //! \param eDataType datatype
+  //! \param pData raw data
+  //! \param iRank number of dimensions
+  //! \param piDim pointer to the dimensions array
+  //! \param piStart if not null pointer to the start position of this subset
   NexusDataSet(NexusDataType eDataType, void *pData, int iRank, int *piDim, int *piStart=NULL);
 
-  /// Destructor
-  /// @note the data pointor is also deleted do not delete it another time
+  //! Destructor
+  //! \remark the data pointor is also deleted do not delete it another time
   ~NexusDataSet();
 
-  /// Free data block
-  ///
+  //! Free data block
   void FreeData();
 
-  /// Clears data set
+  //! Clears data set
   void Clear();
 
-  /// Allocate the data set, according to the NexusDataSetInfo part
-  ///
+  //! Allocate the data set, according to the NexusDataSetInfo part
   void Alloc();
 
-  /// Gives ownership or not
-  ///
-  /// By default the NexusDataset own the data pointer
-  /// @param this_has_ownership if false the NexusDataset is no longer the owner
-  ///
+  //! Gives ownership or not. By default the NexusDataset own the data pointer
+  //!
+  //! \param this_has_ownership if false the NexusDataset is no longer the owner
   void SetOwner(bool this_has_ownership);
 
-  /// Have ownership on data buffer ?
-  ///
-  /// By default the NexusDataset own the data pointer
-  /// @param this_has_ownership if false the NexusDataset is no longer the owner
-  ///
+  //! Have ownership on data buffer ?
+  //!
   bool IsOwner() { return m_owner; }
 
   //-----------------------------------------------------------------
-  /// @name Accessors
+  //! \name Accessors
   //@{
 
-  /// Returns a pointer to the data set
+  //! Returns a pointer to the data set
   void *Data() const { return m_pData; }
 
-  /// Returns size of the data block (i.e. Size() * sizeof(<datatype>) )
+  //! Returns size of the data block (i.e. Size() * sizeof(<datatype>) )
   unsigned int MemSize() const;
 
-  /// Returns the number of items
+  //! Returns the number of items
   unsigned int Size() const;
 
-  /// Sets datas
-  ///
-  /// @param pParam data pointer we take ownership
-  ///
+  //! Sets data
+  //!
+  //! \param pData data pointer we take ownership
   void SetData(void *pData) { m_pData = pData; }
 
-  /// Sets datas
-  ///
-  /// @param pData      Pointer to data to copy
-  /// @param eDataType  Data type
-  /// @param iRank      Number of dimension
-  /// @param piDimArray Dimensions sizes
-  ///
+  //! Sets data
+  //!
+  //! \param pData      Pointer to data to copy
+  //! \param eDataType  Data type
+  //! \param iRank      Number of dimension
+  //! \param piDimArray Dimensions sizes
   void SetData(const void *pData, NexusDataType eDataType, int iRank, int *piDimArray);
 
-  /// Sets one dimension size
-  ///
-  /// iDim  Dimension in range [0, 32[
-  /// iSize Dimension size
-  ///
+  //! Sets one dimension size
+  //!
+  //! \param iDim  Dimension in range [0, 32[
+  //! \param iSize Dimension size
   void SetDimension(int iDim, int iSize);
 
   //@} Accessors
 
   //=============================================================================
-  /// Basic iterator to browse over NeXusDataSet values
+  //! Basic iterator to browse over NeXusDataSet values
   //=============================================================================
   template <class T> class Iterator
   {
@@ -373,13 +393,15 @@ public:
     char *m_pDataItem;
 
   public:
-    /// Constructor
+    //! Constructor
+    //!
+    //! \param DataSet data set on which the iterator will iterate
     Iterator(const NexusDataSet &DataSet) : m_DataSet(DataSet)
     {
       m_pDataItem = (char *)DataSet.Data();
     }
 
-    /// Return current value
+    //! Return current value
     T Value() const
     {
       switch( m_DataSet.DataType() )
@@ -404,24 +426,24 @@ public:
       return T(0);
     }
 
-    /// Dereferencing operator
+    //! Dereferencing operator
     T operator *() { return Value(); }
 
-    /// Post-incrementation operator
+    //! Post-incrementation operator
     Iterator operator++(int)
     {
       m_pDataItem += m_DataSet.DatumSize();
       return *this;
     }
 
-    /// Pre-incrementation operator
+    //! Pre-incrementation operator
     Iterator operator++()
     {
       m_pDataItem += m_DataSet.DatumSize();
       return *this;
     }
 
-    /// Is end of buffer reached ?
+    //! Is end of buffer reached ?
     bool End() const
     {
       return m_pDataItem == (char *)m_DataSet.Data() + m_DataSet.MemSize();
@@ -430,10 +452,10 @@ public:
 };
 
 //=============================================================================
-/// NeXus item info
-///
-/// This class is used to store info about founded groups while
-/// browsing a group level
+//! NeXus item info
+//!
+//! This class is used to store info about founded groups while
+//! browsing a group level
 //=============================================================================
 class NEXUSCPP_DECL NexusItemInfo
 {
@@ -446,45 +468,45 @@ private:
   void          *m_pContext;      // Extra Data storing current context
 
 public:
-  /// Constructor
+  //! Constructor
   NexusItemInfo();
 
-  /// Destructor
+  //! Destructor
   ~NexusItemInfo();
 
   //-----------------------------------------------------------------
   /// Accessors
   //@{
 
-  /// Returns name of NeXus data item (group or set)
+  //! Returns name of NeXus data item (group or set)
   const char *ItemName() const { return m_pszItem; }
 
-  /// Returns class name of NeXus group
+  //! Returns class name of NeXus group
   const char *ClassName() const { return m_pszClass; }
 
-  /// Returns the data type
+  //! Returns the data type
   NexusDataType DataType() const { return m_eDataType; }
 
-  /// Returns 'true' id the item is a data set
+  //! Returns 'true' id the item is a data set
   bool IsDataSet() const;
 
-  /// Returns 'true' id the item is a group
+  //! Returns 'true' id the item is a group
   bool IsGroup() const;
 
   //@} Accessors
 };
 
-/// Smart pointer definition helper
+//! Smart pointer definition helper
 typedef yat::SharedPtr<NexusItemInfo> NexusItemInfoPtr;
 
-/// ItemInfo smart pointers list definition helper
+//! ItemInfo smart pointers list definition helper
 typedef std::list<NexusItemInfoPtr> NexusItemInfoList;
 
 //=============================================================================
-/// NeXus Attribute info
-///
-/// This class is used to store info about founded attributes while browsing
-/// a group level
+//! NeXus Attribute info
+//!
+//! This class is used to store info about founded attributes while browsing
+//! a group level
 //=============================================================================
 class NEXUSCPP_DECL NexusAttrInfo
 {
@@ -498,16 +520,13 @@ protected:
 
 public:
 #if ! defined(OBSOLETE_HDF5_WORKAROUND)
-  /// Constructor
+  //! Constructor
   NexusAttrInfo();
 
-  /// Destructor
+  //! Destructor
   ~NexusAttrInfo();
 #else
-  /// Constructor
   NexusAttrInfo() {};
-
-  /// Destructor
   ~NexusAttrInfo() {};
 #endif
 
@@ -515,23 +534,23 @@ public:
   /// Accessors
   //@{
 
-  /// Returns name of NeXus attribute
+  //! Returns name of NeXus attribute
   const char *AttrName() const { return m_pszName; }
 
-  /// Returns len of attribute
+  //! Returns len of attribute
   int Len() const { return m_iLen; }
 
-  /// Returns type attribute data
+  //! Returns type attribute data
   NexusDataType DataType() const { return m_eDataType; }
 
   //@} Accessors
 };
 
 //=============================================================================
-/// NeXus Attribute
-///
-/// This class is used to store info about founded attributes while browsing
-/// a group level
+//! NeXus Attribute
+//!
+//! This class is used to store info about founded attributes while browsing
+//! a group level
 //=============================================================================
 class NEXUSCPP_DECL NexusAttr: public NexusAttrInfo
 {
@@ -539,60 +558,74 @@ private:
   void    * m_pAttrValue;
 
 public:
+  //! c-tor
+  //!
+  //! \param strName attribute name
   NexusAttr(const std::string &strName);
+
+  //! Copy c-tor
   NexusAttr(const NexusAttr &aAttr);
   ~NexusAttr();
 
-  /// Sets a value of type 'long'
+  //! Sets a value of type 'long'
   void SetLong(long lValue);
 
-  /// Sets a value of type 'C characters std::string'
+  //! Sets a value of type
+  //!
+  //! \param pcszValue C-style string attribute value
   void SetCString(const char *pcszValue);
 
-  /// Sets a value of type 'STL std::string'
+  //! Sets a value of type 'STL std::string'
+  //!
+  //! \param strValue attribute value
   void SetString(const std::string &strValue);
 
-  /// Sets a value of type 'double'
+  //! Sets a value of type 'double'
+  //!
+  //! \param dValue attribute value
   void SetDouble(double dValue);
 
-  /// Sets a value of type 'float'
+  //! Sets a value of type 'float'
+  //!
+  //! \param fValue attribute value
   void SetFloat(float fValue);
 
-  /// Get 'long' type value
+  //! Get 'long' type value
   long GetLong() const;
 
-  /// Gets 'double' type value
+  //! Gets 'double' type value
   double GetDouble() const ;
 
-  /// Gets 'float' type value
+  //! Gets 'float' type value
   float GetFloat() const;
 
-  /// Gets 'std::string' type value
+  //! Gets 'std::string' type value
   std::string GetString() const;
 
-  /// Returns the attr buffer
+  //! Returns the attr buffer
   void *RawValue() const;
 
 private:
   void CopyValue(const NexusAttr &aAttr);
 };
 
-/// definition of a attribute collection
+//! definition of a attribute collection
 typedef std::list<NexusAttr> NeXusAttrList;
 
 //=============================================================================
-/// NeXus File Class
-///
-/// This class allow manipulation of NeXus File with no need to known about
-/// nexus file handle
-/// @note This is wrapper class, the real job is make by a internal objet
+//! NeXus File Class
+//!
+//! This class allow manipulation of NeXus File with no need to known about
+//! nexus file handle
+//! \remark This is wrapper class, the real job is make by a internal objet
 //=============================================================================
 class NEXUSCPP_DECL NexusFile
 {
 public:
+  //! Files open mode
   enum OpenMode
   {
-    NONE,
+    NONE, //! no mode specified
     READ,
     WRITE
   };
@@ -605,24 +638,23 @@ public:
 
   static const bool USE_LOCK = true;
 
-  /// Initialize the HDF5 context
-  /// It is safe to call this function multiple times
-  /// @note Any constructed NexusFile will initialize
-
+  // Initialize the HDF5 context
   static void Initialize();
 
 #if ! defined(OBSOLETE_HDF5_WORKAROUND)
-  /// @name Constructors and destructor
+  //! \name Constructors and destructor
   //@{
 
-  /// Constructor
-  ///
-  /// @param pcszFullPath path + complete filename
+  //! Constructor
+  //!
+  //! \param pcszFullPath path + complete filename
+  //! \param eMode OpenMode (NONE/READ/WRITE)
+  //! \param use_lock if 'true' then use file-system locking for each file access
   NexusFile(const char *pcszFullPath=NULL, OpenMode eMode = NONE, bool use_lock = false);
 
-  /// Destructor
-  ///
-  /// Perform all operations needed such as closing open groups
+  //! Destructor
+  //!
+  //! Perform all operations needed such as closing open groups
   ~NexusFile();
 
 #else
@@ -633,99 +665,93 @@ public:
   //@}
 
   //-----------------------------------------------------------------
-  /// @name File manipulation methods
+  //! \name File manipulation methods
   //@{
 
-  /// Creating file
-  ///
-  /// Create Nexus file based on HDF4 library
-  ///
-  /// @param pcszFullPath path + complete filename
-  /// @param eMode creating mode can be NX_HDF4, NX_HDF5 or NX_XML
-  ///
+  //! Creating file
+  //!
+  //! Create Nexus file
+  //!
+  //! \param pcszFullPath path + complete filename
+  //! \param eMode creating mode can be NX_HDF5, NX_HDF4 or NX_XML
+  //! \remark  HDF4 and XML file modes are deprecated
+  //!
   void Create(const char *pcszFullPath, ENexusCreateMode eMode = NX_HDF5);
 
-  /// Opens an existing file for read operations
-  ///
-  /// @param pcszFullPath path + complete filename
-  ///
+  //! Opens an existing file for read operations
+  //!
+  //! \param pcszFullPath path + complete filename
   void OpenRead(const char *pcszFullPath);
 
-  /// Opens an existing file for read/write operations
-  ///
-  /// @param pcszFullPath path + complete filename
-  ///
+  //! Opens an existing file for read/write operations
+  //!
+  //! \param pcszFullPath path + complete filename
   void OpenReadWrite(const char *pcszFullPath);
 
-  /// Closes currently opened file
-  /// Frees all allocated objects (groups & data sets)
-  ///
+  //! Closes currently opened file
+  //! Frees all allocated objects (groups & data sets)
   void Close();
 
-  /// Flush
-  /// Flushes all data to the NeXus file
-  ///
+  //! Flushes all data to the NeXus file
   void Flush();
 
   //@}
 
   //-----------------------------------------------------------------
-  /// @name groups manipulations
+  //! \name groups manipulations
   //@{
 
-  /// Adds a new group
-  ///
-  /// The new group is added under the currently opened group
-  /// If no group is already open add the group at the top-level
-  /// (hope this is a NXentry group)
-  ///
-  /// @param pcszName  Group name
-  /// @param pcszClass NeXus class
-  /// @param bOpen    If 'true' automatically open the group
-  ///
+  //! Adds a new group
+  //!
+  //! The new group is added under the currently opened group
+  //! If no group is already open add the group at the top-level
+  //! (hope this is a NXentry group)
+  //!
+  //! \param pcszName  Group name
+  //! \param pcszClass NeXus class
+  /// \param bOpen    If 'true' automatically open the group
   void CreateGroup(const char *pcszName, const char *pcszClass, bool bOpen=true);
 
-  /// Opens a existing group
-  ///
-  /// @param pcszName  Group name
-  /// @param pcszClass NeXus class
-  /// @param bThrowException if true this method may throw a exception
-  /// @return
-  ///
+  //! Opens a existing group
+  //!
+  //! \param pcszName  Group name
+  //! \param pcszClass NeXus class
+  //! \param bThrowException if true this method may throw a exception
+  //! \return
   bool OpenGroup(const char *pcszName, const char *pcszClass, bool bThrowException=true);
 
-  /// Closes current group
-  ///
+  //! Closes current group
   void CloseGroup();
 
-  /// Closes all opened groups
-  ///
+  //! Closes all opened groups
   void CloseAllGroups();
 
   //@} groups manipulations
 
   //-----------------------------------------------------------------
-  /// @name data sets manipulations
+  //! \name data sets manipulations
   //@{
 
-  /// Creates data set
-  ///
-  /// @param pcszName Data set name
-  /// @param eDataType Data type
-  /// @param iRank Data set rank
-  /// @param piDim Pointer to array of dimensions
-  ///
+  //! Creates data set
+  //!
+  //! \param pcszName Data set name
+  //! \param eDataType Data type
+  //! \param iRank Data set rank
+  //! \param piDim Pointer to array of dimensions
+  //! \param bOpen If 'true' keep the data set open after its creation
   void CreateDataSet(const char *pcszName, NexusDataType eDataType,
                      int iRank, int *piDim, int bOpen=true);
 
-  /// Creates compressed data set
-  ///
-  /// @param pcszName Data set name
-  /// @param eDataType Data type (see napi.h)
-  /// @param iRank Data set rank
-  /// @param piDim Pointer to array of dimensions
-  /// @param piChunkDim Pointer to array of chunk dimensions
-  ///
+  //! Creates compressed data set
+  //!
+  //! \param pcszName Data set name
+  //! \param eDataType Data type (see napi.h)
+  //! \param iRank Data set rank
+  //! \param piDim Pointer to array of dimensions
+  //! \param piChunkDim Pointer to array of chunk dimensions
+  //! \param filter compression filter to apply
+  //! \param filter_config filter parameters
+  //! \param bOpen If 'true' keep the data set open after its creation
   void CreateCompressedDataSet(const char *pcszName, NexusDataType eDataType,
                                int iRank, int *piDim, int *piChunkDim,
                                CompressionFilter filter=CompressZLIB,
@@ -735,227 +761,246 @@ public:
   ///
   void CloseDataSet();
 
-  /// Quickly creates simple data set and writes the data
-  ///
-  /// @param pcszName Data set name
-  /// @param pData pointer to value
-  /// @param piDim Pointer to array of dimensions sizes
-  /// @param eDataType NeXus Data type (see napi.h)
-  /// @param iRank Dimensions count
-  /// @param bCreate true for creating the dataset before write data otherwise
-  ///        we suppose the dataset already created and opened
-  ///
+  //! Writes data into a new or existing dataset
+  //!
+  //! \param pcszName Data set name
+  //! \param pData pointer to value
+  //! \param eDataType NeXus Data type (see napi.h)
+  //! \param iRank Dimensions count
+  //! \param piDim Pointer to array of dimensions sizes
+  //! \param bCreate true for creating the dataset before write data otherwise
+  //!        we suppose the dataset already created and opened
   void WriteData(const char *pcszName, void *pData, NexusDataType eDataType,
                  int iRank, int *piDim, bool bCreate=true);
 
+  //! Writes data into a new or existing dataset
+  //!
+  //! \param pcszName Data set name
+  //! \param pData pointer to value
+  //! \param eDataType NeXus Data type (see napi.h)
+  //! \param Shape Dimensions arrau
+  //! \param bCreate true for creating the dataset before write data otherwise
+  //!        we suppose the dataset already created and opened
   void WriteData(const char *pcszName, void *pData, NexusDataType eDataType,
                  const std::vector<std::size_t>& Shape, bool bCreate=true);
 
+  //! Writes data subset into a new or existing dataset
+  //!
+  //! \param pcszName Data set name
+  //! \param pData pointer to value
+  //! \param eDataType NeXus Data type
+  //! \param iRank Dimensions count
+  //! \param piStart Pointer to array of start positions of the subset
+  //! \param piDim Pointer to array of dimensions sizes
+  //! \param bCreate true for creating the dataset before write data otherwise
+  //!        we suppose the dataset already created and opened
+  //! \param bNoDim deprecated parameter, must be 'false'
   void WriteDataSubSet(const char *pcszName, void *pData, NexusDataType eDataType,
                        int iRank, int *piStart, int *piDim, bool bCreate=true, bool bNoDim = false);
 
-  /// 'float' version of #WriteData
+  //! 'float' version of #WriteData
   void WriteData(const char *pcszName, float fValue, bool bCreate=true);
 
-  /// 'double' version of #WriteData
+  //! 'double' version of #WriteData
   void WriteData(const char *pcszName, double dValue, bool bCreate=true);
 
-  /// 'long' version of #WriteData
+  //! 'long' version of #WriteData
   void WriteData(const char *pcszName, long lValue, bool bCreate=true);
 
-  /// 'std::string' version of #WriteData
+  //! 'std::string' version of #WriteData
   void WriteData(const char *pcszName, const char *pcszValue, bool bCreate=true);
 
-  /// 'binary' version of #WriteData
+  //! 'binary' version of #WriteData
   void WriteData(const char *pcszName, void *pData, int _iLen, bool bCreate=true);
 
-  /// Opens a already existing data set
-  ///
-  /// @param pcszName Data set name
+  //! Opens a already existing data set
+  //!
+  //! \param pcszName Data set name
+  //! \param bThrowException If 'true' thrown an exception in case of error
   bool OpenDataSet(const char *pcszName, bool bThrowException=true);
 
-  /// Puts data in the currently open data set
-  ///
-  /// @param pData Pointer to the data bloc
-  /// @param pcszName Data set name
-  ///
-  /// @note Use pcszName to specify another data set
-  ///
+  //! Puts data in the currently open data set
+  //!
+  //! \param pData Pointer to the data bloc
+  //! \param pcszName Data set name
+  //! \param bFlush If 'true' then immediately flush the data to the file
+  //! \remark Use pcszName to specify another data set
   void PutData(void *pData, const char *pcszName=NULL, int bFlush=false);
 
-  /// Puts data subset in the currently open data set
-  ///
-  /// @param pData Pointer to the data bloc
-  /// @param piStart Indices of starting values in each dimension
-  /// @param piSize Length of subset in each dimension
-  /// @param pcszName Data set name
-  ///
-  /// @note Use pcszName to specify another data set
-  ///
+  //! Puts data subset in the currently open data set
+  //!
+  //! \param pData Pointer to the data bloc
+  //! \param piStart Indices of starting values in each dimension
+  //! \param piSize Length of subset in each dimension
+  //! \param pcszName Data set name
+  //! \remark Use pcszName to specify another data set
   void PutDataSubSet(void *pData, int *piStart, int *piSize, const char *pcszName=NULL);
 
   //-----------------------------------------------------------------
-  /// @name Data set reading
+  //! \name Data set reading
   //@{
 
-  /// Reads data values from a data set in currently open group
-  ///
-  /// @param pDataSet a pointer to a NexusDataSet instanciate by caller
-  /// @param pcszDataSet Data set name
-  /// @note if the data set name isn't provided, supposes that pDataSet isn't empty
-  ///
+  //! Reads data values from a data set in currently open group
+  //!
+  //! \param pDataSet a pointer to a NexusDataSet instanciate by caller
+  //! \param pcszDataSet Data set name
+  //! \remark if the data set name isn't provided, supposes that pDataSet isn't empty
   void GetData(NexusDataSet *pDataSet, const char *pcszDataSet=NULL);
 
-  /// Reads data values from a data set in currently open group
-  ///
-  /// @param pDataSet a pointer to a NexusDataSet instanciate by caller
-  /// @param pcszDataSet Data set name
-  /// @note if the data set name isn't provided, supposes that pDataSet isn't empty
-  ///
+  //! Reads data values from a data set in currently open group
+  //!
+  //! \param pDataSet a pointer to a NexusDataSet instanciate by caller
+  //! \param pcszDataSet Data set name
+  //! \note if the data set name isn't provided, supposes that pDataSet isn't empty
   void GetDataSubSet(NexusDataSet *pDataSet, const char *pcszDataSet=NULL);
 
-  /// Gets info about a data set
-  ///
-  /// @param pDataSetInfo a pointer to a NexusDataSetInfo instanciate by caller
-  /// @param pcszDataSet Data set name
-  ///
+  //! Gets info about a data set
+  //!
+  //! \param pDataSetInfo a pointer to a NexusDataSetInfo instanciate by caller
+  //! \param pcszDataSet Data set name
   void GetDataSetInfo(NexusDataSetInfo *pDataSetInfo, const char *pcszDataSet);
 
   //@} data sets manipulations
 
   //-----------------------------------------------------------------
-  /// @name Getting attributes
+  //! \name Getting attributes
   //@{
 
-  /// Gets a attribute
-  ///
-  /// @param pcszAttr Attribute name
-  /// @param piBufLen Pointer to BufLen
-  /// @param pData Pointer to attribute value buffer
-  /// @param eDataType Attribute data value type
-  ///
-  /// @note The caller is responsible for allocating enough memory
-  ///       for the attribute values
+  //! Gets a attribute
+  //!
+  //! \param pcszAttr Attribute name
+  //! \param piBufLen Pointer to BufLen
+  //! \param pData Pointer to attribute value buffer
+  //! \param eDataType Attribute data value type
+  //!
+  //! \remark The caller is responsible for allocating enough memory
+  //!         for the attribute values
   void GetAttribute(const char *pcszAttr, int *piBufLen, void *pData,
                     NexusDataType eDataType);
 
-  /// Gets a 'long' attribute. Call
-  ///
-  /// @param pcszAttr Attribute name
-  /// @param plValue Pointer to attribute value buffer
-  ///
-  /// @note The caller is responsible for allocating enough memory
-  ///       for the attribute values
+  //! Gets a 'long' attribute. Call
+  //!
+  //! \param pcszAttr Attribute name
+  //! \param plValue Pointer to attribute value buffer
+  //!
+  //! \remark The caller is responsible for allocating enough memory
+  //!       for the attribute values
   void GetAttribute(const char *pcszAttr, long *plValue);
 
-  /// Gets a 'double' attribute
-  ///
-  /// @param pcszAttr Attribute name
-  /// @param pdValue Pointer to attribute value buffer
-  ///
-  /// @note The caller is responsible for allocating enough memory
-  ///       for the attribute values
+  //! Gets a 'double' attribute
+  //!
+  //! \param pcszAttr Attribute name
+  //! \param pdValue Pointer to attribute value buffer
+  //!
+  //! \remark The caller is responsible for allocating enough memory
+  //!       for the attribute values
   void GetAttribute(const char *pcszAttr, double *pdValue);
 
-  /// Gets a 'float' attribute
-  ///
-  /// @param pcszAttr Attribute name
-  /// @param pfValue Pointer to attribute value buffer
-  ///
-  /// @note The caller is responsible for allocating enough memory
-  ///       for the attribute values
+  //! Gets a 'float' attribute
+  //!
+  //! \param pcszAttr Attribute name
+  //! \param pfValue Pointer to attribute value buffer
+  //!
+  //! \remark The caller is responsible for allocating enough memory
+  //!       for the attribute values
   void GetAttribute(const char *pcszAttr, float *pfValue);
 
-  /// Gets a 'std::string' attribute
-  ///
-  /// @param pcszAttr Attribute name
-  /// @param pstrValue Pointer to attribute value
-  ///
+  //! Gets a 'std::string' attribute
+  //!
+  //! \param pcszAttr Attribute name
+  //! \param pstrValue Pointer to attribute value
   void GetAttribute(const char *pcszAttr, std::string *pstrValue);
 
   //@} Getting attributes
 
   //-----------------------------------------------------------------
-  /// @name Putting attributes
-  /// Writes an attribute of the currently open data set.
-  /// If no data set is open, a global attribute is generated.
-  /// The attribute has both a name and a value.
-  /// @param pcszName Data set name
-  /// @param pValue pointer to value
-  /// @param iLen Value buffer length
-  /// @param eDataType NeXus Data type (see napi.h)
+  //! \name Putting attributes
+  //! Writes an attribute of the currently open data set.
+  //! If no data set is open, a global attribute is generated.
+  //! The attribute has both a name and a value.
   //@{
 
-  /// Generic method for putting attribute
+  //! Generic method for putting attribute
+  //!
+  //! \param pcszName Data set name
+  //! \param pValue pointer to value
+  //! \param iLen Value buffer length
+  //! \param eDataType NeXus Data type (see napi.h)
   void PutAttr(const char *pcszName, void *pValue, int iLen, NexusDataType eDataType);
 
-  /// Puts a attribute of type 'long'
+  //! Puts a attribute of type 'long'
+  //!
+  //! \param pcszName attribute name
+  //! \param lValue attribute value
   void PutAttr(const char *pcszName, long lValue);
 
-  /// Puts a attribute of type 'std::string'
+  //! Puts a attribute of type 'C-style string'
+  //!
+  //! \param pcszName attribute name
+  //! \param pcszValue attribute value
   void PutAttr(const char *pcszName, const char *pcszValue);
 
-  /// Puts a attribute of type 'double'
+  //! Puts a attribute of type 'double'
+  //!
+  //! \param pcszName attribute name
+  //! \param dValue attribute value
   void PutAttr(const char *pcszName, double dValue);
 
-  /// Puts a attribute of type 'float'
+  //! Puts a attribute of type 'float'
+  //!
+  //! \param pcszName attribute name
+  //! \param fValue attribute value
   void PutAttr(const char *pcszName, float fValue);
 
   //@} // Putting attributes
 
   //-----------------------------------------------------------------
-  /// @name Browsing methods
+  //! \name Browsing methods
   //@{
 
-  /// Get the number of items in the current group
+  //! Get the number of items in the current group
   int ItemCount();
 
-  /// Get the number of attributes in the current data set
+  //! Get the number of attributes in the current data set
   int AttrCount();
 
-  /// Get info about the first item (data set or group) in the current group
-  ///
-  /// @param pItemInfo Pointer to NexusItemInfo used to store info
-  ///
-  /// @return NX_OK if data set found
-  ///         NX_EOD if not
-  ///
+  //! Get info about the first item (data set or group) in the current group
+  //!
+  //! \param pItemInfo Pointer to NexusItemInfo used to store info
+  //! \return NX_OK if data set found
+  //!         NX_EOD if not
   int GetFirstItem(NexusItemInfo *pItemInfo);
 
-  /// Get info about the next item (data set or group) in the current group
-  ///
-  /// @param pItemInfo Pointer to NexusItemInfo used to store info
-  ///
-  /// @return NX_OK if data set found
-  ///         NX_EOD if not
-  ///
+  //! Get info about the next item (data set or group) in the current group
+  //!
+  //! \param pItemInfo Pointer to NexusItemInfo used to store info
+  //! \return NX_OK if data set found
+  //!         NX_EOD if not
   int GetNextItem(NexusItemInfo *pItemInfo);
 
-  /// Get info about the first attribute of the specified data set
-  ///
-  /// @param pAttrInfo Pointer to a NexusAttrInfo object
-  /// @param pcszDataSet Name of the data set to search in
-  /// @return NX_OK if group found,
-  ///         NX_EOD if not
-  ///
-  /// @note if pcszDataSet is NULL searching will be performed in currently open
-  /// data set or in global attribute std::list if no data set is open
-  /// @note You must call GetFirstAttribute in order to initialize the search process
-  /// then call GetNextAttribute for retrieving information about the remaining
-  /// attributes
-  ///
+  //! Get info about the first attribute of the specified data set
+  //!
+  //! \param pAttrInfo Pointer to a NexusAttrInfo object
+  //! \param pcszDataSet Name of the data set to search in
+  //! \return NX_OK if group found,
+  //!         NX_EOD if not
+  //!
+  //! \remark if pcszDataSet is NULL searching will be performed in currently open
+  //! data set or in global attribute std::list if no data set is open
+  //! \remark You must call GetFirstAttribute in order to initialize the search process
+  //! then call GetNextAttribute for retrieving information about the remaining
+  //! attributes
   int GetFirstAttribute(NexusAttrInfo *pAttrInfo, const char *pcszDataSet=NULL);
 
-  /// Get info about the next attribute of the specified data set
-  ///
-  /// @param pAttrInfo Pointer to a NexusAttrInfo object
-  /// @return NX_OK if group found
-  ///         NX_EOD if not
-  ///
-  /// @note You must call GetFirstAttribute in order to initialize the search process
-  /// then call GetNextAttribute for retrieving information about the remaining
-  /// attributes
-  ///
+  //! Get info about the next attribute of the specified data set
+  //!
+  //! \param pAttrInfo Pointer to a NexusAttrInfo object
+  //! \return NX_OK if group found
+  //!         NX_EOD if not
+  //!
+  //! \remark You must call GetFirstAttribute in order to initialize the search process
+  //! then call GetNextAttribute for retrieving information about the remaining
+  //! attributes
   int GetNextAttribute(NexusAttrInfo *pAttrInfo);
 
   //@} // Browsing methods
@@ -964,204 +1009,180 @@ public:
   /// @name Item linking methods
   //@{
 
-  /// Get a handle on the currently open data set in order to link it with a group
-  ///
-  /// @return a pointer to the handle, or NULL if no data set is open or no file is open
-  ///
+  //! Get a handle on the currently open data set in order to link it with a group
+  //!
+  //! \return a pointer to the handle, or NULL if no data set is open or no file is open
   void GetDataSetLink(NexusItemID *pnxl);
 
-  /// Get a handle on the currently open group set in order to link it with a group
-  ///
-  /// @return a pointer to the handle, or NULL if no file is open
-  ///
+  //! Get a handle on the currently open group set in order to link it with a group
+  //!
+  //! \return a pointer to the handle, or NULL if no file is open
   void GetGroupLink(NexusItemID *pnxl);
 
-  /// Link a item to the currently open group
-  ///
-  /// @param pItemHandle Handle of the item to link
-  ///
+  //! Link a item to the currently open group
+  //!
+  //! \param nxl Handle of the item to link
   void LinkToCurrentGroup(const NexusItemID &nxl);
 
   //@} // Item linking methods
 
   //-----------------------------------------------------------------
-  /// @name User pointer accessors
+  //! \name User pointer accessors
   //@{
 
-  /// Get user pointer
+  //! Get user pointer
   void *UserPtr() const { return m_pUserPtr; }
 
-  /// Set user pointer
+  //! Set user pointer
   void SetUserPtr(void *p) { m_pUserPtr = p; }
 
   //@} // User pointer accessors
 
   //-----------------------------------------------------------------
-  /// @name high level methods
+  //! \name high level methods
   //@{
 
-  /// Opens a existing group from a given path
-  ///
-  /// @param pszPath   path to group in the form : /<NXroot>/{Group name}<{group class}>/...
-  ///                  if no group name is specified then open the first group for the given class
-  ///                  example : /<NXroot>/scan_1<NXentry>/<NXdata>
-  /// @param bThrowException if true this method may throw a exception
-  /// @return true if group has been succefully open
-  ///
+  //! Opens a existing group from a given path
+  //!
+  //! \param pszPath path to group in the form : /<NXroot>/{Group name}<{group class}>/...
+  //!                if no group name is specified then open the first group for the given class
+  //!                example : "/<NXroot>/scan_1<NXentry>/<NXdata>"
+  //! \param bThrowException if true this method may throw a exception
+  //! \return true if group has been succefully open
   bool OpenGroupPath(const char *pszPath, bool bThrowException=true);
 
-  /// Create and open a group from a given path
-  /// This method may throw a exception
-  ///
-  /// @param pszPath   path to group in the form : /<NXroot>/{Group name}<{group class}>/...
-  ///                  if no group name is specified then open the first group for the given class
-  ///                  example : /<NXroot>/scan_1<NXentry>/<NXdata>
-  ///
+  //! Create and open a group from a given path
+  //! This method may throw a exception
+  //!
+  //! \param pszPath path to group in the form : "/<NXroot>/{Group name}<{group class}>/..."
+  //!                if no group name is specified then open the first group for the given class
+  //!                example : "/<NXroot>/scan_1<NXentry>/<NXdata>"
   bool CreateGroupPath(const char *pszPath);
 
-  /// Search for all occurences of a group (name and class) starting at a given level on the hierarchy
-  ///
-  /// @param pszGroupName name of searched group
-  /// @param pszClassName class of searched group
-  /// @param pvecPaths output std::vector of found groups
-  /// @param pszStartPath path for starting research
-  /// @return NX_OK if at least one group was found
-  ///         NX_EOD if not
-  ///
+  //! Search for all occurences of a group (name and class) starting at a given level on the hierarchy
+  //!
+  //! \param pszGroupName name of searched group
+  //! \param pszClassName class of searched group
+  //! \param pvecPaths output std::vector of found groups
+  //! \param pszStartPath path for starting research
+  //! \return NX_OK if at least one group was found
+  //!         NX_EOD if not
   int SearchGroup(const char *pszGroupName, const char *pszClassName,
                   std::vector<std::string> *pvecPaths, const char *pszStartPath=NULL);
 
-  /// Search for all occurences of a data set (name) with a given attribute
-  ///
-  /// @param pszAttrName name of looked attribute
-  /// @param pvecPaths output std::vector of found data sets
-  /// @param strAttrVal optionnal attribute value to match
-  /// @return NX_OK if at least one data set was found
-  ///         NX_EOD if not
-  ///
+  //! Search for all occurences of a data set (name) with a given attribute
+  //!
+  //! \param pszAttrName name of looked attribute
+  //! \param pvecDataSets output std::vector of found data sets
+  //! \param strAttrVal optionnal attribute value to match
+  //! \return NX_OK if at least one data set was found
+  //!         NX_EOD if not
   int SearchDataSetFromAttr(const char *pszAttrName, std::vector<std::string> *pvecDataSets, const std::string &strAttrVal="");
 
-  /// Search for first occurence of a data set (name) with a given attribute
-  ///
-  /// @param pszAttrName name of looked attribute
-  /// @param pstrDataSet name of founded data set
-  /// @param strAttrVal optionnal attribute value to match
-  /// @return NX_OK if at least one data set was found
-  ///         NX_EOD if not
-  ///
+  //! Search for first occurence of a data set (name) with a given attribute
+  //!
+  //! \param pszAttrName name of looked attribute
+  //! \param pstrDataSet name of founded data set
+  //! \param strAttrVal optionnal attribute value to match
+  //! \return NX_OK if at least one data set was found
+  //!         NX_EOD if not
   int SearchFirstDataSetFromAttr(const char *pszAttrName, std::string *pstrDataSet, const std::string &strAttrVal="");
 
-  /// Search for all occurences of a data set (name) with a given attribute
-  ///
-  /// @param pszAttrName name of looked attribute
-  /// @param iRank dataset rank
-  /// @param pvecPaths output std::vector of found data sets
-  /// @param strAttrVal optionnal attribute value to match
-  /// @return NX_OK if at least one data set was found
-  ///         NX_EOD if not
-  ///
+  //! Search for all occurences of a data set (name) with a given attribute
+  //!
+  //! \param pszAttrName name of looked attribute
+  //! \param iRank dataset rank
+  //! \param pvecDataSets output std::vector of found data sets
+  //! \param strAttrVal optionnal attribute value to match
+  //! \return NX_OK if at least one data set was found
+  //!         NX_EOD if not
   int SearchDataSetFromAttrAndRank(const char *pszAttrName, int iRank, std::vector<std::string> *pvecDataSets, const std::string &strAttrVal="");
 
-  /// Search for all occurences of a data set (name) with a given attribute
-  ///
-  /// @param pszAttrName name of looked attribute
-  /// @param iRank dataset rank
-  /// @param pvecPaths output std::vector of found data sets
-  /// @param strAttrVal optionnal attribute value to match
-  /// @return NX_OK if at least one data set was found
-  ///         NX_EOD if not
-  ///
+  //! Search for all occurences of a data set (name) with a given attribute
+  //!
+  //! \param pszAttrName name of looked attribute
+  //! \param iRank dataset rank
+  //! \param[out] pstrDataSet dataset name found
+  //! \param strAttrVal optionnal attribute value to match
+  //! \return NX_OK if at least one data set was found
+  //!         NX_EOD if not
   int SearchFirstDataSetFromAttrAndRank(const char *pszAttrName, int iRank, std::string *pstrDataSet, const std::string &strAttrVal="");
 
-  /// Gets a attribute as a std::string regardless of its type
-  ///
-  /// @param aAttrInfo Attribute info object
-  /// @return A STL std::string containing the value
-  ///
+  //! Gets a attribute as a string regardless of its type
+  //!
+  //! \param aAttrInfo Attribute info object
+  //! \return The value as string
   std::string GetAttributeAsString(const NexusAttrInfo &aAttrInfo);
 
-  /// Check if dataset has attribute
-  ///
-  /// @param pszAttrName Name of looked attribute
-  /// @param pcszDataSet (optionnal) Data set to open, if not specified look in currently opened dataset
-  /// @param strAttrVal optionnal attribute value to match
-  /// @return 'true' if sds has attribute, otherwise 'false'
-  ///
+  //! Check if dataset has attribute
+  //!
+  //! \param pszAttrName Name of looked attribute
+  //! \param pcszDataSet (optionnal) Data set to open, if not specified look in currently opened dataset
+  //! \param strAttrVal optionnal attribute value to match
+  //! \return 'true' if sds has attribute, otherwise 'false'
   bool HasAttribute(const char *pszAttrName, const char *pcszDataSet=NULL, const std::string &strAttrVal="");
 
-  /// Gets a attribute as a std::string regardless of its type
-  ///
-  /// @param pszAttrName Attribute name
-  /// @param pcszDataSet Name of the data set containing the attributge
-  /// @param pstrValue std::string object to put the value in
-  /// @return true if attribute was found
-  ///
+  //! Gets a attribute as a std::string regardless of its type
+  //!
+  //! \param pszAttrName Attribute name
+  //! \param pcszDataSet Name of the data set containing the attributge
+  //! \param pstrValue std::string object to put the value in
+  //! \return true if attribute was found
   bool GetAttributeAsString(const char *pszAttrName, const char *pcszDataSet, std::string *pstrValue);
 
-  /// Build a dictionnary that contains axis datasets for each dimension belong to a given dataset
-  /// Entries in the dictionnary are in the form :
-  /// 'axis_<axis>_<primary>' = '<dataset name>
-  ///
-  /// @param vecvecAxis Vector of axis vectors that will contains the axis datasets name
-  /// @param pszGroup Group Path
-  /// @param pszDataSet DataSet name
-  ///
-  /// @return 'true' if at least one axis has been found
-  ///
+  //! Build a dictionnary that contains axis datasets for each dimension belong to a given dataset
+  //! Entries in the dictionnary are in the form :
+  //! "axis_<axis>_<primary>=<dataset name>""
+  //!
+  //! \param pmapAxis Map of axis that will contains the axis datasets name
+  //! \param pszGroupPath Group Path
+  //! \param pcszDataSet DataSet name
+  //! \return 'true' if at least one axis has been found
   bool BuildAxisDict(std::map<std::string, std::string> *pmapAxis, const char *pszGroupPath=NULL, const char *pcszDataSet=NULL);
 
-  /// Build a dictionnary that contains axis values (readed and setted) datasets for each dimension belong to a given dataset
-  /// Entries in the dictionnary are in the form :
-  /// 'axis-readed_<axis>_<primary>' = '<dataset name>
-  /// 'axis-setted_<axis>_<primary>' = '<dataset name>
-  ///
-  /// @param vecvecAxis Vector of axis vectors that will contains the axis datasets name
-  /// @param pszGroup Group Path
-  /// @param pszDataSet DataSet name
-  ///
-  /// @return 'true' if at least one axis has been found
-  ///
+  //! Build a dictionnary that contains axis values (readed and setted) datasets for each dimension belong to a given dataset
+  //! Entries in the dictionnary are in the form :
+  //! "axis-readed_<axis>_<primary> = <dataset name>"
+  //! "axis-setted_<axis>_<primary> = <dataset name>"
+  //!
+  //! \param pmapAxis Map of axis that will contains the axis datasets name
+  //! \param pszGroupPath Group Path
+  //! \param pcszDataSet DataSet name
+  //! \return 'true' if at least one axis has been found
   bool BuildScanAxisDict(std::map<std::string, std::string> *pmapAxis, const char *pszGroupPath=NULL, const char *pcszDataSet=NULL);
 
-  /// Get scam dimension
-  ///
-  /// Reads NXdata group and look for variables datasets (with attribute axis) and return the
-  /// biggest axis attribute value (note that in time scan case axis may be seeted to 0)
-  ///
-  /// @param pszGroup Group Path
-  ///
-  /// @return scan dimension (time scans are 1D scans), or 0 if no axis datasets was found
-  ///
+  //! Get scam dimension
+  //!
+  //! Reads NXdata group and look for variables datasets (with attribute axis) and return the
+  //! biggest axis attribute value (note that in time scan case axis may be seeted to 0)
+  //!
+  //! \param pszDataGroupPath Group Path
+  //!
+  //! \return scan dimension (time scans are 1D scans), or 0 if no axis datasets was found
   int GetScanDim(const char *pszDataGroupPath);
 
-  /// Current Group Name
-  ///
+  //! Current Group Name
   std::string CurrentGroupName();
 
-  /// Current Group Class
-  ///
+  //! Current Group Class
   std::string CurrentGroupClass();
 
-  /// Currently opened group path inside NeXus file
-  ///
+  //! Currently opened group path inside NeXus file
   std::string CurrentGroupPath();
 
-  /// Currently opened dataset
-  ///
+  //! Currently opened dataset
   std::string CurrentDataset();
 
-  /// Returns the children of the currently opened group
-  ///
-  /// @param pvecDatasets empty std::vector for storing dataset names
-  /// @param pvecGroupNames empty std::vector for storing subgroups names
-  /// @param pvecGroupClasses empty std::vector for storing subgroups classes
-  ///
+  //! Returns the children of the currently opened group
+  //!
+  //! \param pvecDatasets empty std::vector for storing dataset names
+  //! \param pvecGroupNames empty std::vector for storing subgroups names
+  //! \param pvecGroupClasses empty std::vector for storing subgroups classes
   void GetGroupChildren(std::vector<std::string> *pvecDatasets, std::vector<std::string> *pvecGroupNames, std::vector<std::string> *pvecGroupClasses);
 
-  /// Returns the children of the currently opened group
-  ///
-  /// @return a list of NexusItemInfo object smart pointer (yat::SharedPtr)
-  ///
+  //! Returns the children of the currently opened group
+  //!
+  //! \return a list of NexusItemInfo object smart pointer (yat::SharedPtr)
   NexusItemInfoList GetGroupChildren();
 
   //@}
@@ -1170,7 +1191,7 @@ public:
   /// @name Deprecated methods
   //@{
 
-  void GetAttribute(const char *pcszAttr, char *pszValue, int iBufLen);
+  void GetAttribute(const char*, char*, int);
 
   //@}
 
diff --git a/include/nexuscpp/nxfinalizer.h b/include/nexuscpp/nxfinalizer.h
index a851aef..4ccd2e3 100644
--- a/include/nexuscpp/nxfinalizer.h
+++ b/include/nexuscpp/nxfinalizer.h
@@ -1,11 +1,20 @@
-// ============================================================================
-// = CONTEXT
-// Flyscan Project - Nexus file generation optimizer
-// = File
-// NexusDataStreamerFinalizer.h
-// = AUTHOR
-// N.Leclercq - SOLEIL
-// ============================================================================
+//*****************************************************************************
+/// Synchrotron SOLEIL
+///
+/// NeXus C++ API
+///
+/// Creation : 16/02/2005
+/// Authors  : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud
+///
+/// This program is free software; you can redistribute it and/or modify it under
+/// the terms of the GNU General Public License as published by the Free Software
+/// Foundation; version 2 of the License.
+///
+/// This program is distributed in the hope that it will be useful, but WITHOUT
+/// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+/// FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+///
+//*****************************************************************************
 
 #pragma once
 
@@ -19,13 +28,11 @@ namespace nxcpp
 
 const std::size_t kDEFAULT_PULSER_PERIOD = 3000;
 
-//-----------------------------------------------------------------------------
 // Forward declaration
-//-----------------------------------------------------------------------------
 class DataStreamer;
 
 //-----------------------------------------------------------------------------
-// NexusDataStreamerFinalizer
+//! NexusDataStreamerFinalizer
 //-----------------------------------------------------------------------------
 class NEXUSCPP_DECL NexusDataStreamerFinalizer
 {
@@ -33,28 +40,28 @@ public:
 
   typedef struct Entry
   {
-    //----------------------------------------
-    //- the nexuscpp::DataStreamer to finalize
+    //! The nexuscpp::DataStreamer to finalize
     nxcpp::DataStreamer *data_streamer;
-    //----------------------------------------
-    //- opaque data holder
-    //-   for data-items making use of the nexuscpp::DataStreamer::NO_COPY mode
-    //-   this will be simply deleted once the data streaming is done
-    //-   use this to ensure that the memory blocks containing data are not released before streaming is done
+
+    //! Opaque data holder
+    //!   for data-items making use of the nexuscpp::DataStreamer::NO_COPY mode
+    //!   this will be simply deleted once the data streaming is done
+    //!   use this to ensure that the memory blocks containing data are not released before streaming is done
     yat::Container *data_holder;
-    //----------------------------------------
-    Entry ()
-      : data_streamer(0), data_holder(0) {}
-    //----------------------------------------
-    Entry (Entry& src)
-      : data_streamer(src.data_streamer), data_holder(src.data_holder) { src.data_streamer = 0; src.data_holder = 0; }
-    //----------------------------------------
+
+    //! default c-tor
+    Entry () : data_streamer(0), data_holder(0) {}
+
+    //! Copy c-tot
+    Entry (Entry& src) : data_streamer(src.data_streamer), data_holder(src.data_holder)
+      { src.data_streamer = 0; src.data_holder = 0; }
+
+    //! Copy operator
     void operator= (Entry& src)
       { data_streamer = src.data_streamer; src.data_streamer = 0; data_holder = src.data_holder; src.data_holder = 0; }
-    //----------------------------------------
-    ~Entry ()
-      { delete data_streamer; delete data_holder; }
-    //----------------------------------------
+
+    //! d-tor
+    ~Entry () { delete data_streamer; delete data_holder; }
   } Entry;
 
   //-------------------------------------------------------
@@ -63,14 +70,15 @@ public:
   //-------------------------------------------------------
   virtual ~NexusDataStreamerFinalizer();
 
-  //-------------------------------------------------------
-  //! \param pulser_period finalizer period in ms
+  //! Start the finalyser
+  //!
+  //! \param period_ms finalizer period in ms
   void start(std::size_t period_ms = kDEFAULT_PULSER_PERIOD);
 
-  //-------------------------------------------------------
+  //! Stop the finalyser
   void stop();
 
-  //-------------------------------------------------------
+  //! Push a datastreamer entry
   void push(Entry* e);
 
 private:
diff --git a/include/nexuscpp/nxwriter.h b/include/nexuscpp/nxwriter.h
index 7845a1d..6e594ce 100644
--- a/include/nexuscpp/nxwriter.h
+++ b/include/nexuscpp/nxwriter.h
@@ -1,10 +1,10 @@
 //*****************************************************************************
 /// Synchrotron SOLEIL
 ///
-/// NeXus C++ API over NAPI
+/// NeXus C++ API
 ///
-/// Creation : 2010/07/18
-/// Author   : Stephane Poirier
+/// Creation : 16/02/2005
+/// Authors  : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud
 ///
 /// This program is free software; you can redistribute it and/or modify it under
 /// the terms of the GNU General Public License as published by the Free Software
@@ -19,6 +19,27 @@
 #ifndef __NX_WRITER_H__
 #define __NX_WRITER_H__
 
+// ============================================================================
+//! \page highlevelPage High level NeXus API documentation
+//! \tableofcontents
+//!
+//! \section secB1 High level NeXus writing API
+//! The high level writing API provide classes allow writing large datasets in
+//! synchronous or asynchonous mode
+//!
+//! \section secB2 High level NeXus writing classes
+//! Links to classes : \n
+//!   - nxcpp::DatasetWriter
+//!   - nxcpp::GenericDatasetWriter
+//!   - nxcpp::AxisDatasetWriter
+//!   - nxcpp::SignalDatasetWriter
+//!   - nxcpp::NexusFileWriter
+//!   - nxcpp::MMetadata
+//!   - nxcpp::IExceptionHandler
+//!   - nxcpp::IMessageHandler
+//!
+// ============================================================================
+
 // standard library objets
 #include <iostream>
 #include <vector>
@@ -49,7 +70,7 @@ void message_to_console(yat::ELogLevel lvl, const yat::String& msg);
 void exception_to_console(const yat::Exception& e);
 
 //=============================================================================
-/// Mix-in that add metadata capabilitie to objects
+//! Mix-in that add metadata capabilitie to objects
 //=============================================================================
 class MMetadata
 {
@@ -70,118 +91,202 @@ private:
   std::map<std::string, double> m_mapDouble; // "Float" type metadata
 
 public:
-  /// Add std::string metadata
+  //! Add std::string metadata
+  //!
+  //! \param strKey metadata name
+  //! \param strValue metadata value
   void AddMetadata(const std::string &strKey, const std::string &strValue);
-  /// Add C-ansi std::string metadata
+
+  //! Add C-ansi std::string metadata
+  //!
+  //! \param strKey metadata name
+  //! \param pszValue metadata value
   void AddMetadata(const std::string &strKey, const char *pszValue);
-  /// Add integer matedata
+
+  //! Add integer matedata
+  //!
+  //! \param strKey metadata name
+  //! \param iValue metadata value
   void AddMetadata(const std::string &strKey, int iValue);
-  /// Add integer matedata
+
+  //! Add integer matedata
+  //!
+  //! \param strKey metadata name
+  //! \param lValue metadata value
   void AddMetadata(const std::string &strKey, long lValue);
-  /// Add float metadata
+
+  //! Add float metadata
+  //!
+  //! \param strKey metadata name
+  //! \param dValue metadata value
   void AddMetadata(const std::string &strKey, double dValue);
 
-  /// Check metadata
+  //! Check metadata
+  //!
+  //! \param strKey metadata name
   bool HasMetadata(const std::string &strKey) const;
 
-  /// Get metadata as std::string
-  /// Implicitely convert integer and float metadata as std::string value
-  /// @param  bThrow if true throw a exception in case of no data
-  /// @return true if metadata was found, otherwise false (if bThrow == false)
+  //! Get metadata as std::string
+  //! Implicitely convert integer and float metadata as string value
+  //!
+  //! \param strKey metadata name
+  //! \param[out] pstrValue Value as string
+  //! \param  bThrow if true throw a exception in case of no data
+  //! \return true if metadata was found, otherwise false (if bThrow == false)
   bool GetMetadata(const std::string &strKey, std::string *pstrValue, bool bThrow=true) const;
 
-  /// Get std::string metadata
-  /// @param  bThrow if true throw a exception in case of no data
-  /// @return true if metadata was found, otherwise false (if bThrow == false)
+  //! Get string metadata
+  //!
+  //! \param strKey metadata name
+  //! \param[out] pstrValue pointer output value
+  //! \param  bThrow if true throw a exception in case of no data
+  //! \return true if metadata was found, otherwise false (if bThrow == false)
   bool GetStringMetadata(const std::string &strKey, std::string *pstrValue, bool bThrow=true) const;
+
+  //! Get string metadata
+  //!
+  //! \param strKey metadata name
+  //! \return metadata value
+  //! \throw Throw an exception if the key is not found
   std::string StringMetadata(const std::string &strKey) const;
 
-  /// Get integer metadata
-  /// @param  bThrow if true throw a exception in case of no data
-  /// @return true if metadata was found, otherwise false (if bThrow == false)
+  //! Get integer metadata
+  //!
+  //! \param strKey metadata name
+  //! \param[out] piValue pointer output value
+  //! \param  bThrow if true throw a exception in case of no data
+  //! \return true if metadata was found, otherwise false (if bThrow == false)
   bool GetIntegerMetadata(const std::string &strKey, int *piValue, bool bThrow=true) const;
+
+  //! Get integer metadata
+  //!
+  //! \param strKey metadata name
+  //! \return metadata value
+  //! \throw Throw an exception if the key is not found
   int IntegerMetadata(const std::string &strKey) const;
 
-  /// Get long integer metadata
-  /// @param  bThrow if true throw a exception in case of no data
-  /// @return true if metadata was found, otherwise false (if bThrow == false)
+  //! Get long integer metadata
+  //!
+  //! \param strKey metadata name
+  //! \param[out] plValue pointer output value
+  //! \param  bThrow if true throw a exception in case of no data
+  //! \return true if metadata was found, otherwise false (if bThrow == false)
   bool GetLongIntegerMetadata(const std::string &strKey, long *plValue, bool bThrow=true) const;
+
+  //! Get long integer metadata
+  //!
+  //! \param strKey metadata name
+  //! \return metadata value
+  //! \throw Throw an exception if the key is not found
   long LongIntegerMetadata(const std::string &strKey) const;
 
-  /// Get float metadata
-  /// @param  bThrow if true throw a exception in case of no data
-  /// @return true if metadata was found, otherwise false (if bThrow == false)
+  //! Get long float (double-type) metadata
+  //!
+  //! \param strKey metadata name
+  //! \param[out] pdValue pointer output value
+  //! \param  bThrow if true throw a exception in case of no data
+  //! \return true if metadata was found, otherwise false (if bThrow == false)
   bool GetDoubleMetadata(const std::string &strKey, double *pdValue, bool bThrow=true) const;
+
+  //! Get long float (double-type) metadata
+  //!
+  //! \param strKey metadata name
+  //! \return metadata value
+  //! \throw Throw an exception if the key is not found
   double DoubleMetadata(const std::string &strKey) const;
 
-  /// Get type of a metadata from its key name
-  /// @param  bThrow if true throw a exception in case of no data
-  /// @return MMetadata::Type value
+  //! Get type of a metadata from its key name
+  //!
+  //! \param strKey metadata name
+  //! \param  bThrow if true throw a exception in case of no data
+  //! \return MMetadata::Type value
   Type GetMetadataType(const std::string &strKey, bool bThrow=true) const;
 
-  /// Returns the metadata keys std::list
+  //! Returns the metadata keys std::list
   std::list<std::string> MetadataKeys() const;
 
-  /// Clear all metadata
+  //! Clear all metadata
   void ClearMetadata();
 };
 
 //=============================================================================
-/// Exception handling interface
+//! Exception handling interface
 //=============================================================================
 class IExceptionHandler
 {
 public:
+  //! Method to implement
   virtual void OnNexusException(const NexusException &e)=0;
 };
 
 //=============================================================================
-/// Message handling interface
+//! Message handling interface
 //=============================================================================
 class IMessageHandler
 {
 public:
+  //! Method to implement
+  //!
+  //! \param lvl log level as defined in the yat library
+  //! \param msg the message
   virtual void OnNexusMessage(yat::ELogLevel lvl, const yat::String& msg)=0;
 };
 
 //=============================================================================
-/// Synchronous/Asynchronous NeXus Writer File Class
-///
-/// This class allow asynchronous writing into a nexus file
-/// @note This is wrapper class, the real job is make by a internal objet
+//! Synchronous/Asynchronous NeXus Writer File Class
+//!
+//! This class allow asynchronous writing into a nexus file
+//! \remark This is wrapper class, the real job is make by a internal objet
 //=============================================================================
 class NEXUSCPP_DECL NexusFileWriter
 {
 public:
    enum WriteMode
   {
-    SYNCHRONOUS = 0, /// Synchronous mode
-    ASYNCHRONOUS,    /// Asynchronous mode
+    SYNCHRONOUS = 0, //! Synchronous mode
+    ASYNCHRONOUS,    //! Asynchronous mode
 
     ///@{ Depracated modes
-    IMMEDIATE,       /// Asynchronous mode: write data as soon as possible
-    DELAYED          /// Asynchronous mode: data are cached and written at specified time interval
+    IMMEDIATE,
+    DELAYED
     ///@}
   };
 
+  //! Writing speed statistics
   typedef struct Statistics
   {
     Statistics();
     yat::uint64 ui64WrittenBytes;
     yat::uint64 ui64TotalBytes;
-    float       fInstantMbPerSec; /// Instant rate in MBytes/s
-    float       fAverageMbPerSec; /// Average rate in MBytes/s
+    float       fInstantMbPerSec; //! Instant rate in MBytes/s
+    float       fAverageMbPerSec; //! Average rate in MBytes/s
     double      dTotalWriteTime;
   } Statistics;
 
   //=============================================================================
-  /// Write notification interface
+  //! Write notification interface
   //=============================================================================
   class INotify
   {
   public:
+    //! Write subset notification
+    //!
+    //! \param[out] source_p object address who performed the write operation
+    //! \param[out] dataset_path Path to the written dataset
+    //! \param[out] start_pos start position of the subset
+    //! \param[out] dim subset dimensions array
     virtual void OnWriteSubSet(NexusFileWriter* source_p, const std::string& dataset_path, int start_pos[MAX_RANK], int dim[MAX_RANK])=0;
+
+    //! Write whole dataset notification
+    //!
+    //! \param[out] source_p object address who performed the write operation
+    //! \param[out] dataset_path Path to the written dataset
     virtual void OnWrite(NexusFileWriter* source_p, const std::string& dataset_path)=0;
+
+    //! File close notification
+    //!
+    //! \param[out] source_p object address who performed the write operation
+    //! \param[out] nexus_file_path Closed file path
     virtual void OnCloseFile(NexusFileWriter* source_p, const std::string& nexus_file_path)=0;
   };
 
@@ -192,117 +297,116 @@ private:
   static std::size_t s_attempt_delay_ms_;
 
 public:
-  /// Constructor
-  ///
-  /// @param strFilePath path + complete filename
+  //! Constructor
+  //!
+  //! \param strFilePath path + complete filename
+  //! \param eMode Writing mode
+  //! \param uiWritePeriod Write period (seconds) in asynchronous mode
   NexusFileWriter(const std::string &strFilePath, WriteMode eMode=ASYNCHRONOUS, unsigned int uiWritePeriod=2);
 
-  /// Destructor
-  ///
+  //! Destructor
   ~NexusFileWriter();
 
-  /// Set exception handler
-  ///
+  //! Set exception handler
   void SetExceptionHandler(IExceptionHandler *pHandler);
 
-  /// Set message handler
-  ///
+  //! Set message handler
   void SetMessageHandler(IMessageHandler *pHandler);
 
-  /// Set the notification handler
-  ///
+  //! Set the notification handler
   void SetNotificationHandler(INotify *pHandler);
 
-  /// Set the notification handler
-  ///
+  //! Set the notification handler
   void AddNotificationHandler(INotify* pHandler);
 
-  /// Set cache size (in MB) for DELAYED mode
-  ///
+  //! Set cache size (in MB) for DELAYED mode
   void SetCacheSize(yat::uint16 usCacheSize);
 
-  /// Create a dataset
-  ///
-  /// @param strPath  Dataset path and name (ex: entry<NXentry>/sample<NXsample>/formula)
-  /// @param aDataSet The dataset to write
+  //! Create a dataset
+  //!
+  //! \param strPath  Dataset path and name (ex: "entry<NXentry>/sample<NXsample>/formula")
+  //! \param eDataType The data type
+  //! \param iRank number of dimensions
+  //! \param piDim dimensions array
+  //! \param filter Compression filter (no compression is the default)
+  //! \param filter_config Compression filter parameters
+  //! \param piChunk dimensions array of compress chunks (null if no compression)
   void CreateDataSet(const std::string &strPath, NexusDataType eDataType, int iRank,
                      int *piDim, CompressionFilter filter=CompressNone,
                      FilterConfig filter_config=FilterConfig(), int *piChunk=0);
 
-  /// Push a dataset
-  ///
-  /// @param strPath  Dataset path and name (ex: entry<NXentry>/sample<NXsample>/formula)
-  /// @param aDataSet The dataset to write
+  //! Push a dataset
+  //!
+  //! \param strPath  Dataset path and name (ex: "entry<NXentry>/sample<NXsample>/formula")
+  //! \param ptrDataSet Shared pointer to the dataset to push
   void PushDataSet(const std::string &strPath, NexusDataSetPtr ptrDataSet);
 
-  /// Push a attribute
-  /// Dataset must already exists, otherwise a error is repported and action is canceled
-  ///
-  /// @param strPath Dataset path and name (ex: entry<NXentry>/sample<NXsample>/formula.attribute)
-  /// @param aAttr   The attribute
-  ///
+  //! Push a attribute
+  //! Dataset must already exists, otherwise a error is repported and action is canceled
+  //!
+  //! \param strPath Dataset path and name (ex: "entry<NXentry>/sample<NXsample>/formula.attribute")
+  //! \param ptrAttr Shared pointer to the attribute
   void PushDatasetAttr(const std::string &strPath, NexusAttrPtr ptrAttr);
 
-  /// Abort: delete all remaining data if any, no more access to file
-  /// When this method returns
-  ///
+  //! Abort: delete all remaining data if any, no more access to file
+  //! When this method returns
   void Abort();
 
-  /// True
+  //! True
   bool IsError();
 
-  /// Returns true if there is no data to write
+  //! Returns true if there is no data to write
   bool IsEmpty();
 
-  /// Returns true when all job is done
+  //! Returns true when all job is done
   bool Done();
 
-  /// Wait until all job is done
+  //! Wait until all job is done
   void Synchronize(bool bSendSyncMsg=true);
 
-  /// Hold the data, force the NeXuisFileWriter to cache data and not writting it into the filename
-  /// Until either Synchronize() or Hold(false) is calles
-  /// Available only in asynchronous mode
+  // Hold the data, force the NeXuisFileWriter to cache data and not writting it into the filename
+  // Until either Synchronize() or Hold(false) is calles
+  // Available only in asynchronous mode
   void Hold(bool b=true);
 
-  /// Return true if it hold the data
-  /// Make sense only in asynchronous mode
+  // Return true if it hold the data
+  // Make sense only in asynchronous mode
   bool IsHold() const;
 
-  /// File name
+  //! File name
   const std::string &File() const;
 
-  /// The file will not be closed after each write action
+  //! The file will not be closed after each write action
   void SetFileAutoClose(bool b);
 
-  /// Close the nexus file
+  //! Close the nexus file
   void CloseFile();
 
-  /// Engage the file lock mecanism
+  //! Engage the file lock mecanism
   void SetUseLock();
 
   //@{ Attempt values for retry mechanism
 
-    /// Max attempts for write actions
+    //! Max attempts for write actions
     static std::size_t AttemptMax() { return s_attempt_max_; }
 
-    /// delay (in ms) between to attempts
+    //! delay (in ms) between to attempts
     static std::size_t AttemptDelay() { return s_attempt_delay_ms_; }
 
-    /// set max attempts for write actions
+    //! set max attempts for write actions
     static void SetAttemptMax(std::size_t n);
 
-    /// set  (in ms) between to attempts
+    //! set  (in ms) between to attempts
     static void SetAttemptDelay(std::size_t ms);
 
   //@}
 
   //@{ Statistics
 
-    /// Reset all statistics
+    //! Reset all statistics
     void ResetStatistics();
 
-    /// Gets a copy of the statistics
+    //! Gets a copy of the statistics
     Statistics GetStatistics() const;
 
   //@}
@@ -310,19 +414,19 @@ public:
 
 typedef yat::MemBuf DatasetBuf;
 
-// Referenced pointer definition
+//! Referenced pointer definition
 typedef yat::SharedPtr<NexusFileWriter, yat::Mutex> NexusFileWriterPtr;
 
-/// Data shape type
+//! Data shape type
 typedef std::vector<std::size_t> DataShape;
 
 // Empty shape
 extern const DataShape g_empty_shape;
 
 //==============================================================================
-/// DatasetWriter
-///
-/// class containing a NexusDataset with its attributes and its location
+//! DatasetWriter
+//!
+//! class containing a NexusDataset with its attributes and its location
 //==============================================================================
 class NEXUSCPP_DECL DatasetWriter:public MMetadata
 {
@@ -333,17 +437,31 @@ public:
     virtual void OnFlushData(DatasetWriter* pWriter) = 0;
   };
 
+  //! DatasetWriter configuration
   typedef struct Config
   {
-    ///
+    //! Dimensions array of canonical data
     DataShape shape_data_item;
+
+    //! Dimensions array of acquisition space
     DataShape shape_matrix;
+
+    //! Write cache size
     yat::uint16 cache_mb;
+
+    //! useless parameter (to be deleted)
     yat::uint16 write_tmout;
+
+    //! Compress filter
     CompressionFilter compress_filter;
+
+    //! Compress filter parameters
     FilterConfig filter_config;
+
+    //! minimal dataset size for compression, smaller datasets are not compressed
     std::size_t min_bytes_for_compression;
 
+    //! default c-tor
     Config()
     {
       compress_filter = CompressNone;
@@ -385,82 +503,105 @@ private:
   void init(yat::uint16 usMaxMB, yat::uint16 m_usWriteTimeout);
 
 public:
+  //! Sets the NeXus dataset type according to the class invoked through the template
   template <class TYPE>
   void SetDataType();
 
+  //! reset the writer in order to re-using it
   void Reset();
 
+  //! Sets the NeXus dataset type
   void SetNeXusDataType(NexusDataType eDataType);
 
+  //! Set dataset shape
+  //!
+  //! \param shapeDataItem shape of the canonical data
+  //! \param shapeMatrix shape of the acquisition
   void SetShapes(const DataShape &shapeDataItem, const DataShape &shapeMatrix);
 
+  //! Set compression parameters
   void set_compression(CompressionFilter filter=CompressZLIB, FilterConfig filter_config=FilterConfig());
 
-  /// c-tor
+  //! Main constructor
+  //!
+  //! \param shapeDataItem Shape of the canonical data
+  //! \param shapeMatrix Shape of the acquisition
+  //! \param usMaxMB Cache size
+  //! \param m_usWriteTimeout Max time before flushing cached data
   DatasetWriter(const DataShape &shapeDataItem, const DataShape &shapeMatrix=g_empty_shape, yat::uint16 usMaxMB=64, yat::uint16 m_usWriteTimeout=0);
+
+  //! Convenience constructor for 1-D scan
+  //!
+  //! \param shapeDataItem Shape of the canonical data
+  //! \param one_dim_size Scan length
+  //! \param usMaxMB Cache size
+  //! \param m_usWriteTimeout Max time before flushing cached data
   DatasetWriter(const DataShape &shapeDataItem, std::size_t one_dim_size, yat::uint16 usMaxMB=64, yat::uint16 m_usWriteTimeout=0);
+
+  //! Use this constructor when shapes are now known yet
+  //!
+  //! \param usMaxMB Cache size
+  //! \param m_usWriteTimeout Max time before flushing cached data
   DatasetWriter(yat::uint16 usMaxMB=64, yat::uint16 m_usWriteTimeout=0);
   DatasetWriter(const Config& cfg);
 
-  /// @deprecated
-  DatasetWriter(const std::vector<int>& shapeDataItem, const std::vector<int>& shapeMatrix, yat::uint16 usMaxMB=64);
-  DatasetWriter(const std::vector<int> &shapeDataItem, std::size_t one_dim_size, yat::uint16 usMaxMB=64);
+  //@{ Deprecated methods
+    DatasetWriter(const std::vector<int>&, const std::vector<int>&, yat::uint16 usMaxMB=64);
+    DatasetWriter(const std::vector<int>&, std::size_t, yat::uint16 usMaxMB=64);
+  //@}
 
   /// d-tor
   virtual ~DatasetWriter();
 
-  /// Set Nexus file writer object
-  /// Must be called before push any data, like after construction or a call to the Stop method
-  ///
-  /// @param ptrWriter referenced pointer  to the new writer object
-  ///
+  //! Set Nexus file writer object
+  //! Must be called before push any data, like after construction or a call to the Stop method
+  //!
+  //! \param ptrWriter referenced pointer to the new writer object
   void SetNexusFileWriter(NexusFileWriterPtr ptrWriter);
 
-  /// Set the flushing notification listener
-  /// Must be called before push any data, like after construction or a call to the Stop method
-  ///
-  /// @param ptrWriter referenced pointer  to the new writer object
-  ///
+  //! Set the flushing notification listener
+  //! Must be called before push any data, like after construction or a call to the Stop method
+  //!
+  //! \param pListener pointer to the listener
   void SetFlushListener(IFlushNotification* pListener) { m_pFlushListener = pListener; }
 
-  /// Resizes matrix
-  /// Must be called before push any data, like after construction or a call to the Stop method
-  ///
-  /// @param shapeMatrix new shape
-  ///
+  //! Resizes matrix
+  //! Must be called before push any data, like after construction or a call to the Stop method
+  //!
+  //! \param shapeMatrix new shape
   void SetMatrix(const DataShape &shapeMatrix=g_empty_shape);
 
-  /// Change destination path
+  //! Change destination path
   void SetPath(const std::string &strPath, const std::string &strDataset);
 
-  /// Change destination path
+  //! Change destination path
   void SetFullPath(const std::string &strFullPath);
 
-  /// Set the dataset name
+  //! Set the dataset name
   void SetDatasetName(const std::string &strDatasetName);
 
-  /// Sets the buffer size in Mega bytes
+  //! Sets the buffer size in Mega bytes
   void SetCacheSize(yat::uint16 usMaxMB) { m_usMaxMB = usMaxMB; }
 
-  /// Adding integer-type attribute to the NeXus dataset
+  //! Adding integer-type attribute to the NeXus dataset
   void AddAttribute(const NexusAttrPtr &ptrAttr);
 
-  /// Adding double-type attribute to the NeXus dataset
+  //! Adding double-type attribute to the NeXus dataset
   void AddFloatAttribute(const std::string &strName, double dValue);
 
-  /// Adding integer-type attribute to the NeXus dataset
+  //! Adding integer-type attribute to the NeXus dataset
   void AddIntegerAttribute(const std::string &strName, long lValue);
 
-  /// Adding std::string-type attribute to the NeXus dataset
+  //! Adding std::string-type attribute to the NeXus dataset
   void AddStringAttribute(const std::string &strName, const std::string &strValue);
 
-  /// Push data
+  //! Push data
   void PushData(const void *pData, std::size_t nDataCount=1, bool bNoCopy=false);
 
-  /// No more data to push, data is flushed to the NeXus file writer
+  //! No more data to push, data is flushed to the NeXus file writer
   void Stop();
 
-  /// Cancel => forget all
+  //! Cancel => forget all
   void Abort();
 
   //@{ Accessors
@@ -477,59 +618,71 @@ public:
   //@}
 };
 
-// Referenced pointer definition
+//! Shared pointer definition
 typedef yat::SharedPtr<DatasetWriter, yat::Mutex> DatasetWriterPtr;
 
 //==============================================================================
-/// GenericDatasetWriter
-///
-/// class containing a NexusDataset with its attributes and its location
+//! GenericDatasetWriter
+//!
+//! Typed DatasetWriter  class
 //==============================================================================
 template <class TYPE>
 class GenericDatasetWriter: public DatasetWriter
 {
 public:
-  /// c-tor
+  //! c-tor
+  //! \param shapeDataItem Shape of the canonical data
+  //! \param shapeMatrix Shape of the acquisition
+  //! \param usMaxMB Cache size
   GenericDatasetWriter(const DataShape &shapeDataItem, const DataShape &shapeMatrix=g_empty_shape, unsigned short usMaxMB=100);
 
-  /// d-tor
+  //! d-tor
   ~GenericDatasetWriter() {}
-
 };
 
 //==============================================================================
-/// AxisDatasetWriter
-///
-/// class containing a NexusDataset with its attributes and its location
+//! AxisDatasetWriter
+//!
+//! Typed DatasetWriter class dedicated to for axis data
 //==============================================================================
 template <class TYPE>
 class AxisDatasetWriter: public DatasetWriter
 {
 public:
-  /// c-tor
+  //! c-tor
+  //! \param iDim Dimension number of axis
+  //! \param iSize Dimension length
+  //! \param iOrder Axis order in the dimension
   AxisDatasetWriter(int iDim, int iSize, int iOrder=1);
 
-  /// d-tor
+  //! d-tor
   ~AxisDatasetWriter() {}
 
   void PushPosition(TYPE TValue);
 };
 
 //==============================================================================
-/// SignalDatasetWriter
-///
-/// class containing a NexusDataset with its attributes and its location
+//! SignalDatasetWriter
+//!
+//! class containing a NexusDataset with its attributes and its location
+//! Typed DatasetWriter class dedicated to for signal data
 //==============================================================================
 template <class TYPE>
 class SignalDatasetWriter: public DatasetWriter
 {
 public:
-  /// c-tor
+  //! c-tor
+  //! \param shapeData Shape of the canonical data
+  //! \param shapeMatrix Shape of the acquisition
+  //! \param iSignal axis order in the dimension
   SignalDatasetWriter(const DataShape &shapeData, const DataShape &shapeMatrix=g_empty_shape, int iSignal=1);
 
-  /// d-tor
+  //! d-tor
   ~SignalDatasetWriter() {}
 
+  //! Push one position
+  //!
+  //! \param pValue pointer to the position value
   void PushSignal(TYPE *pValue);
 };
 
diff --git a/licence.txt b/licence.txt
new file mode 100644
index 0000000..65c5ca8
--- /dev/null
+++ b/licence.txt
@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
diff --git a/src/nxhdf5.cpp b/src/nxhdf5.cpp
index 4636cf3..bfc5f02 100755
--- a/src/nxhdf5.cpp
+++ b/src/nxhdf5.cpp
@@ -4,7 +4,7 @@
 /// NeXus C++ API
 ///
 /// Creation : 16/02/2005
-/// Author   : Stephane Poirier
+/// Authors  : Stephane Poirier, Clement Rodriguez, Nicolas Leclerc, Julien Berthaud
 ///
 /// This program is free software; you can redistribute it and/or modify it under
 /// the terms of the GNU General Public License as published by the Free Software
diff --git a/src/nxwriter.cpp b/src/nxwriter.cpp
index d33621f..49212e3 100644
--- a/src/nxwriter.cpp
+++ b/src/nxwriter.cpp
@@ -1514,6 +1514,7 @@ void NexusFileWriter::Synchronize(bool bSendSyncMsg)
 
   if( NexusFileWriter::SYNCHRONOUS != m_pImpl->WriteMode() )
   {
+    //## clarifier
     if( NexusFileWriter::DELAYED == m_pImpl->WriteMode() )
     {
       m_pImpl->post(new yat::Message(NexusFileWriterImpl::PROCESS_CACHE));
-- 
GitLab