Merge pull request #371 from williamfgc/docs

Update doxygen and readme docs

ReadMe.md

@@ -6,8 +6,8 @@
 [![Travis CI](https://travis-ci.org/ornladios/ADIOS2.svg)](https://travis-ci.org/ornladios/ADIOS2)
 [![AppVeyor CI](https://ci.appveyor.com/api/projects/status/0s2a3qp57hgbvlhj?svg=true)](https://ci.appveyor.com/project/ornladios/adios2)
 
-# Adaptable Input / Output System (ADIOS) v2.0
-This is v2.0 of the ADIOS I/O system, developed as part of the
+# Adaptable Input / Output System (ADIOS) v2.1.0
+This is v2.1.0 of the ADIOS I/O system, developed as part of the
 U.S. Department of Energy Exascale Computing Program.
 
 ## License
@@ -19,8 +19,10 @@ Copyright.txt for more details.
 * cmake - Project specific CMake modules
 * examples - ADIOS2 Examples
 * scripts - Project maintenance and development scripts
-* source - Main ADIOS2 source
-* bindings - Additional language bindings (currently only Python is available)
+* source - Main ADIOS2 source  
+    * adios2 - source directory for the ADIOS2 library to be installed    under install-dir/lib/libadios2.  
+    * utils  - source directory for the binary utilities, to be installed under install-dir/bin  
+* bindings - Additional language bindings (C, Fortran and Python)
 * testing - Tests
 
 ## Documentation
@@ -56,13 +58,13 @@ $ mkdir build
 
 ```bash
 $ cd build
-$ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios2/2.0.0/gnu/openmpi ../source
+$ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios2/2.1.0/gnu/openmpi ../source
 -- The C compiler identification is GNU 6.3.1
 -- The CXX compiler identification is GNU 6.3.1
 ...
 
 ADIOS2 build configuration:
-  ADIOS Version: 2.0.0
+  ADIOS Version: 2.1.0
   C++ Compiler : GNU 6.3.1
     /usr/bin/c++
 
@@ -101,9 +103,8 @@ The following options can be specified with CMake's `-DVAR=VALUE` syntax to cont
 | `ADIOS2_USE_HDF5`    | **`AUTO`**/``ON``/``OFF`` | Enable the [HDF5](https://www.hdfgroup.org) engine.                              |
 | `ADIOS2_USE_ADIOS1`  | **`AUTO`**/``ON``/``OFF`` | Enable the [ADIOS 1.x](https://www.olcf.ornl.gov/center-projects/adios/) engine. |
 | `ADIOS2_USE_Python`  | **`AUTO`**/``ON``/``OFF`` | Enable the Python >= 2.7 bindings. |
-| `ADIOS2_USE_C`       | **`AUTO`**/``ON``/``OFF`` | Enable the C bindings library libadios2_c.so or libadios2_c.a |
 
-Note: The `ADIOS2_USE_HDF5` and `ADIOS2_USE_ADIOS1` options require the use of a matching serial or parallel version depending on whether `ADIOS2_USE_MPI` is enabled.  SImilary, enabling MPI and Python bindings requires the presence of `mpi4py`.
+Note: The `ADIOS2_USE_HDF5` and `ADIOS2_USE_ADIOS1` options require the use of a matching serial or parallel version depending on whether `ADIOS2_USE_MPI` is enabled.  Similary, enabling MPI and Python bindings requires the presence of `mpi4py`.
 
 In addition to the `ADIOS2_USE_Feature` options, the following options are also available to control how the library get's built:
 
@@ -168,15 +169,15 @@ $ make install
 ...
 Install the project...
 -- Install configuration: "Debug"
--- Installing: /opt/adios2/2.0.0/gnu/openmpi/include/adios2/ADIOSConfig.h
+-- Installing: /opt/adios2/2.1.0/gnu/openmpi/include/adios2/ADIOSConfig.h
 ...
--- Installing: /opt/adios2/2.0.0/gnu/openmpi/bin/adios2-config
+-- Installing: /opt/adios2/2.1.0/gnu/openmpi/bin/adios2-config
 ...
--- Installing: /opt/adios2/2.0.0/gnu/openmpi/include/adios2.h
+-- Installing: /opt/adios2/2.1.0/gnu/openmpi/include/adios2.h
 ...
--- Installing: /opt/adios2/2.0.0/gnu/openmpi/lib/libadios2.so.2.0.0
--- Installing: /opt/adios2/2.0.0/gnu/openmpi/lib/libadios2.so.2
--- Installing: /opt/adios2/2.0.0/gnu/openmpi/lib/libadios2.so
+-- Installing: /opt/adios2/2.1.0/gnu/openmpi/lib/libadios2.so.2.0.0
+-- Installing: /opt/adios2/2.1.0/gnu/openmpi/lib/libadios2.so.2
+-- Installing: /opt/adios2/2.1.0/gnu/openmpi/lib/libadios2.so
 ...
 $
 ```

doc/ReadMe.md

-# Documentation for the Adaptable Input / Output System (ADIOS) v2.0
+# Documentation for the Adaptable Input / Output System (ADIOS) v2.1.0
 
 # Generate Doxygen API
 

source/adios2/core/ADIOS.h

@@ -38,18 +38,24 @@ public:
     /**
      * @brief Constructor for MPI applications WITH a XML config file
      * @param configFile XML format (maybe support different formats in the
-     * future?)
-     * @param mpiComm MPI communicator from application
-     * @param debugMode true: extra exception checks (recommended)
+     * future (json)?)
+     * @param mpiComm MPI communicator from application, make sure is valid
+     * through the scope of adios2 calls
+     * @param debugMode true (default): extra exception checks (recommended),
+     * false: optional feature to turn off checks on user input data,
+     * recommended in stable flows
      */
     ADIOS(const std::string configFile, MPI_Comm mpiComm,
           const bool debugMode = true, const std::string hostLanguage = "C++");
 
     /**
-     * @brief Constructor for non-MPI applications WITH a XML config file
+     * @brief Constructor for non-MPI applications WITH a XML config file (it
+     * must end with extension .xml)
      * @param configFile XML format (maybe support different formats in the
-     * future?)
-     * @param debugMode true: extra exception checks (recommended)
+     * future (json)?)
+     * @param debugMode true (default): extra exception checks (recommended),
+     * false: optional feature to turn off checks on user input data,
+     * recommended in stable flows
      */
     ADIOS(const std::string configFile, const bool debugMode = true,
           const std::string hostLanguage = "C++");
@@ -57,14 +63,18 @@ public:
     /**
      * @brief Constructor for MPI apps WITHOUT a XML config file
      * @param mpiComm MPI communicator from application
-     * @param debugMode true: extra exception checks (recommended)
+     * @param debugMode true (default): extra exception checks (recommended),
+     * false: optional feature to turn off checks on user input data,
+     * recommended in stable flows
      */
     ADIOS(MPI_Comm mpiComm, const bool debugMode = true,
           const std::string hostLanguage = "C++");
 
     /**
      *  @brief ADIOS no-MPI default empty constructor
-     *  @param debugMode true: extra exception checks (recommended)
+     * @param debugMode true (default): extra exception checks (recommended),
+     * false: optional feature to turn off checks on user input data,
+     * recommended in stable flows
      */
     ADIOS(const bool debugMode = true, const std::string hostLanguage = "C++");
 
@@ -80,8 +90,9 @@ public:
     /**
      * Declares a new IO class object and returns a reference to that object.
      * @param ioName must be unique
-     * @return reference to newly created IO object inside ADIOS, if IO is
-     * declared it throws an exception
+     * @return reference to newly created IO object inside current ADIOS object
+     * @exception std::invalid_argument if IO with unique name is already
+     * declared, in debug mode only
      */
     IO &DeclareIO(const std::string name);
 
@@ -90,7 +101,9 @@ public:
      * Follow the C++11 STL containers at function.
      * @param name of IO to look for
      * @return if IO exists returns a reference to existing IO object inside
-     * ADIOS, otherwise throws an exception
+     * ADIOS
+     * @exception std::invalid_argument if IO was not created with DeclareIO, in
+     * debug mode only
      */
     IO &AtIO(const std::string name);
 
@@ -103,6 +116,8 @@ public:
      * @param type from derived class
      * @param parameters optional parameters
      * @return reference to Operator object
+     * @exception std::invalid_argument if Operator with unique name is already
+     * defined, in debug mode only
      */
     Operator &DefineOperator(const std::string name, const std::string type,
                              const Params &parameters = Params());
@@ -111,8 +126,10 @@ public:
      * Signature for passing Callback functions as operators
      * @param name unique operator name
      * @param function callable function
-     * @param parameters
+     * @param parameters optional key-value pairs parameters
      * @return reference to Operator object
+     * @exception std::invalid_argument if Operator with unique name is already
+     * defined, in debug mode only
      */
     template <class R, class... Args>
     Operator &DefineOperator(const std::string name,

source/adios2/core/Attribute.h

@@ -21,8 +21,8 @@ class Attribute : public AttributeBase
 {
 
 public:
-    std::vector<T> m_DataArray;
-    T m_DataSingleValue;
+    std::vector<T> m_DataArray; ///< holds data for array attributes
+    T m_DataSingleValue;        ///< holds data for single value attributes
 
     /**
      * Data array constructor

source/adios2/core/Engine.h

@@ -46,13 +46,14 @@ public:
 public:
     /**
      * Unique Base class constructor
+     * @param engineType derived class identifier
      * @param io object that generates this Engine
      * @param name unique engine name within IO class object
-     * @param openMode  open mode from ADIOSTypes.h OpenMode
+     * @param mode  open mode from ADIOSTypes.h Mode
      * @param mpiComm new communicator passed at Open or from ADIOS class
      */
     Engine(const std::string engineType, IO &io, const std::string &name,
-           const Mode openMode, MPI_Comm mpiComm);
+           const Mode mode, MPI_Comm mpiComm);
 
     virtual ~Engine() = default;
 
@@ -63,6 +64,14 @@ public:
     IO &GetIO() noexcept;
 
     StepStatus BeginStep();
+
+    /**
+     * Indicates the beginning of a step. Typically used for streaming and
+     * inside step loops.
+     * @param mode stepping mode
+     * @param timeoutSeconds (not yet implemented)
+     * @return current step status
+     */
     virtual StepStatus BeginStep(StepMode mode,
                                  const float timeoutSeconds = 0.f);
 
@@ -119,7 +128,7 @@ public:
      *               not reusable until PerformPuts
      * </pre>
      * @param variable input object with metadata
-     * @param value single value passed by value
+     * @param value single value passed by value, allows rvalues
      */
     template <class T>
     void PutSync(Variable<T> &variable, const T &value);
@@ -178,6 +187,7 @@ public:
 
     /** Execute all Put<Deferred,T> starting from a previous PerformPuts */
     virtual void PerformPuts();
+
     /** Execute all Get<Deferred,T> starting from a previous PerformGets */
     virtual void PerformGets();
 
@@ -192,7 +202,8 @@ public:
     void WriteStep();
 
     /**
-     * Closes a particular transport, or all if -1
+     * Closes a particular transport, or all if -1. This is a purely virtual
+     * function that all engines must implement.
      * @param transportIndex order from IO AddTransport
      */
     virtual void Close(const int transportIndex = -1) = 0;

source/adios2/core/IO.cpp

@@ -433,9 +433,9 @@ Engine &IO::Open(const std::string &name, const Mode mode, MPI_Comm mpiComm)
     return *itEngine.first->second.get();
 }
 
-Engine &IO::Open(const std::string &name, const Mode openMode)
+Engine &IO::Open(const std::string &name, const Mode mode)
 {
-    return Open(name, openMode, m_MPIComm);
+    return Open(name, mode, m_MPIComm);
 }
 
 // PRIVATE

source/adios2/core/IO.h

@@ -69,14 +69,16 @@ public:
     /** From AddTransport, parameters in map for each transport in vector */
     std::vector<Params> m_TransportsParameters;
 
-    /** From Add Operator */
+    /** From AddOperator, contains operators added to this IO */
     std::vector<OperatorInfo> m_Operators;
 
     /**
-     * Constructor called from ADIOS factory class
+     * @brief Constructor called from ADIOS factory class DeclareIO function.
+     * Not to be used direclty in applications.
      * @param name unique identifier for this IO object
      * @param mpiComm MPI communicator from ADIOS factory class
      * @param inConfigFile IO defined in config file (XML)
+     * @param hostLanguage current language using the adios2 library
      * @param debugMode true: extra exception checks (recommended)
      */
     IO(const std::string name, MPI_Comm mpiComm, const bool inConfigFile,
@@ -85,34 +87,35 @@ public:
     ~IO() = default;
 
     /**
-     * Sets the engine type for this IO class object
-     * @param engine
+     * @brief Sets the engine type for this IO class object
+     * @param engine predefined engine type, default is bpfile
      */
     void SetEngine(const std::string engine) noexcept;
 
-    /** Set the IO mode (collective or independent)
+    /**
+     * @brief Set the IO mode (collective or independent), not yet implemented
      * @param IO mode */
     void SetIOMode(const IOMode mode);
 
     /**
-     * Version that passes a map to fill out parameters
+     * @brief Version that passes a map to fill out parameters
      * initializer list = { "param1", "value1" },  {"param2", "value2"},
      * @param params adios::Params std::map<std::string, std::string>
      */
     void SetParameters(const Params &parameters = Params()) noexcept;
 
     /**
-     * Sets a single parameter overwriting value if key exists;
+     * @brief Sets a single parameter overwriting value if key exists;
      * @param key parameter key
      * @param value parameter value
      */
     void SetParameter(const std::string key, const std::string value) noexcept;
 
-    /** Retrieve current parameters map */
+    /** @brief Retrieve current parameters map */
     Params &GetParameters() noexcept;
 
     /**
-     * Adds a transport and its parameters for the IO Engine
+     * @brief Adds a transport and its parameters for the IO Engine
      * @param type must be a supported transport type
      * @param params acceptable parameters for a particular transport
      * @return transportIndex handler
@@ -121,9 +124,10 @@ public:
                               const Params &parameters = Params());
 
     /**
-     * Set a single parameter to an existing transport identified with a
-     * transportIndex handler from AddTransport. This function overwrites
-     * existing parameter.
+     * @brief Sets a single parameter to an existing transport identified with a
+     * transportIndex handler from AddTransport.
+     * This function overwrites
+     * existing parameter with the same key.
      * @param transportIndex index handler from AddTransport
      * @param key parameter key
      * @param value parameter value
@@ -132,7 +136,7 @@ public:
                                const std::string key, const std::string value);
 
     /**
-     * Define a Variable of primitive data type for I/O.
+     * @brief Define a Variable of primitive data type for current IO.
      * Default (name only) is a local single value,
      * in order to be compatible with ADIOS1.
      * @param name variable name, must be unique within Method
@@ -142,6 +146,8 @@ public:
      * @param constantShape true if dimensions, offsets and local sizes don't
      * change over time
      * @return reference to Variable object
+     * @exception std::invalid_argument if Variable with unique name is already
+     * defined, in debug mode only
      */
     template <class T>
     Variable<T> &
@@ -150,73 +156,90 @@ public:
                    const bool constantDims = false, T *data = nullptr);
 
     /**
-     * Define attribute from contiguous data array owned by an application
+     * @brief Define attribute from contiguous data array owned by an
+     * application
      * @param name must be unique for the IO object
      * @param array pointer to user data
      * @param elements number of data elements
      * @return reference to internal Attribute
+     * @exception std::invalid_argument if Attribute with unique name is already
+     * defined, in debug mode only
      */
     template <class T>
     Attribute<T> &DefineAttribute(const std::string &name, const T *array,
                                   const size_t elements);
 
     /**
-     * Define attribute from a single variable making a copy
+     * @brief Define attribute from a single variable making a copy
      * @param name must be unique for the IO object
      * @param value single data value
      * @return reference to internal Attribute
+     * @exception std::invalid_argument if Attribute with unique name is already
+     * defined, in debug mode only
      */
     template <class T>
     Attribute<T> &DefineAttribute(const std::string &name, const T &value);
 
     /**
-     * Removes an existing Variable
+     * @brief Removes an existing Variable in current IO object.
+     * Dangerous function since references and
+     * pointers can be dangling after this call.
      * @param name unique identifier input
      * @return true: found and removed variable, false: not found, nothing to
      * remove
      */
     bool RemoveVariable(const std::string &name) noexcept;
 
-    /** Removes all existing variables in current IO object */
+    /**
+     * @brief Removes all existing variables in current IO object.
+     * Dangerous function since references and
+     * pointers can be dangling after this call.
+     */
     void RemoveAllVariables() noexcept;
 
     /**
-     * Removes an existing Attribute. Dangerous function since references and
+     * @brief Removes an existing Attribute in current IO object.
+     * Dangerous function since references and
      * pointers can be dangling after this call.
      * @param name unique identifier input
      * @return true: found and removed attribute, false: not found, nothing to
      * remove
-      */
+     */
     bool RemoveAttribute(const std::string &name) noexcept;
 
-    /** Removes all existing attributes in current IO object. Dangerous function
-     *  since references and pointers can be dangling after this call. */
+    /**
+     * @brief Removes all existing attributes in current IO object.
+     * Dangerous function since references and
+     * pointers can be dangling after this call.
+     */
     void RemoveAllAttributes() noexcept;
 
     /**
-     * Map with variables info: key: name, value: type
-     * @return populate map with current variables
+     * @brief Retrieve map with variables info. Use when reading.
+     * @return map with current variables and info
+     * keys: Type, Min, Max, Value, AvailableStepsStart,
+     * AvailableStepsCount, Shape, Start, Count, SingleValue
      */
     std::map<std::string, Params> GetAvailableVariables() noexcept;
 
     /**
-     * Gets an existing variable of primitive type by name
+     * @brief Gets an existing variable of primitive type by name
      * @param name of variable to be retrieved
-     * @return reference to an existing variable created with DefineVariable
-     * throws an exception if Variable is not found
+     * @return pointer to an existing variable in current IO, nullptr if not
+     * found
      */
     template <class T>
     Variable<T> *InquireVariable(const std::string &name) noexcept;
 
     /**
-     * Returns the type of an existing variable as an string
+     * @brief Returns the type of an existing variable as an string
      * @param name input variable name
-     * @return type
+     * @return type primitive type
      */
     std::string InquireVariableType(const std::string &name) const noexcept;
 
     /**
-     * Retrieves hash holding variable identifiers
+     * Retrieves hash holding internal variable identifiers
      * @return
      * <pre>
      * key: unique variable name,
@@ -227,7 +250,7 @@ public:
     const DataMap &GetVariablesDataMap() const noexcept;
 
     /**
-     * Retrieves hash holding Attributes identifiers
+     * Retrieves hash holding internal Attributes identifiers
      * @return
      * <pre>
      * key: unique attribute name,
@@ -240,24 +263,27 @@ public:
     /**
      * Gets an existing attribute of primitive type by name
      * @param name of attribute to be retrieved
-     * @return nullptr if not found, else pointer reference to exising attribute
+     * @return pointer to an existing attribute in current IO, nullptr if not
+     * found
      */
     template <class T>
     Attribute<T> *InquireAttribute(const std::string &name) noexcept;
 
     /**
-     * Map with variables info: key: name, value: type
-     * @return populate map with current variables
+     * @brief Retrieve map with attributes info. Use when reading.
+     * @return map with current attributes and info
+     * keys: Type, Elements, Value
      */
     std::map<std::string, Params> GetAvailableAttributes() noexcept;
 
     /**
-     * Check existence in config file passed to ADIOS class
-     * @return true: defined in config file
+     * @brief Check existence in config file passed to ADIOS class constructor
+     * @return true: defined in config file, false: not found in config file
      */
     bool InConfigFile() const noexcept;
 
-    /** Sets declared to true if IO exists in code created with ADIOS DeclareIO
+    /**
+     * Sets declared to true if IO exists in code created with ADIOS DeclareIO
      */
     void SetDeclared() noexcept;
 
@@ -271,35 +297,47 @@ public:
      * Adds an operator defined by the ADIOS class. Could be a variable set
      * transform, callback function, etc.
      * @param adiosOperator operator created by the ADIOS class
-     * @param parameters specific parameters for IO
+     * @param parameters specific parameters for current IO
      */
     void AddOperator(Operator &adiosOperator,
                      const Params &parameters = Params()) noexcept;
 
     /**
-     * Creates a polymorphic object that derives the Engine class,
+     * @brief Creates a polymorphic object that derives the Engine class,
      * based on the SetEngine function or config file input
      * @param name unique engine identifier within IO object
-     * (file name in case of File transports)
-     * @param openMode write, read, append from ADIOSTypes.h OpenMode
+     * (e.g. file name in case of Files)
+     * @param mode write, read, append from ADIOSTypes.h Mode
      * @param mpiComm assigns a new communicator to the Engine
-     * @return a smart pointer to a derived object of the Engine class
+     * @return a reference to a derived object of the Engine class
+     * @exception std::invalid_argument if Engine with unique name is already
+     * created with another Open, in debug mode only
      */
-    Engine &Open(const std::string &name, const Mode openMode,
-                 MPI_Comm mpiComm);
+    Engine &Open(const std::string &name, const Mode mode, MPI_Comm mpiComm);
 
     /**
      * Overloaded version that reuses the MPI_Comm object passed
      * from the ADIOS class to the IO class
      * @param name unique engine identifier within IO object
      * (file name in case of File transports)
-     * @param openMode write, read, append from ADIOSTypes.h OpenMode
-     * @return a smart pointer to a derived object of the Engine class
+     * @param mode write, read, append from ADIOSTypes.h OpenMode
+     * @return a reference to a derived object of the Engine class
+     * @exception std::invalid_argument if Engine with unique name is already
+     * created with another Open, in debug mode only
      */
-    Engine &Open(const std::string &name, const Mode openMode);
+    Engine &Open(const std::string &name, const Mode mode);
 
-    // READ FUNCTIONS:
+    // READ FUNCTIONS, not yet implemented:
+    /**
+     * not yet implented
+     * @param pattern
+     */
     void SetReadMultiplexPattern(const ReadMultiplexPattern pattern);
+
+    /**
+     * not yet implemented
+     * @param mode
+     */
     void SetStreamOpenMode(const StreamOpenMode mode);
 
 private:

source/adios2/core/Variable.h

@@ -42,8 +42,10 @@ public:
 
     ~Variable<T>() = default;
 
+    /** Gets current data pointer for this Variable object */
     T *GetData() const noexcept;
 
+    /** Sets current data pointer for this Variable object */
     void SetData(const T *) noexcept;
 
 private:

source/adios2/core/VariableBase.h

@@ -134,7 +134,7 @@ public:
     size_t GetAvailableStepsCount() const;
 
     /**
-     * Pushed a new transform to a sequence of transports
+     * Pushed a new transform to a sequence of transports. Not yet implemented.
      * @param transform reference to an object derived from the Transform class
      * @param parameters transform specific parameters
      * @return transformID handler