Merge branch 'issue/add_documentation' into 'master'

added some comments to functions and classes

See merge request spraetor/dune-vtk!15

dune/vtk/datacollectorinterface.hh

@@ -3,12 +3,18 @@
 #include <cstdint>
 #include <vector>
 
-namespace Dune {
-
-template <class GridView, class Derived, class Partition>
-class DataCollectorInterface
+namespace Dune
 {
-public:
+  /// Base class for data collectors in a CRTP style.
+  /**
+   * \tparam GridView   Model of Dune::GridView
+   * \tparam Derived    Implementation of a concrete DataCollector.
+   * \tparam Partition  Dune::PartitionType [Partitions::InteriorBorder]
+   **/
+  template <class GridView, class Derived, class Partition>
+  class DataCollectorInterface
+  {
+  public:
     /// The partitionset to collect data from
     static constexpr auto partition = Partition{};
 
@@ -18,7 +24,7 @@ public:
     /// The dimension of the world
     enum { dow = GridView::dimensionworld };
 
-public:
+  public:
     /// Store a copy of the GridView
     DataCollectorInterface (GridView const& gridView)
       : gridView_(gridView)
@@ -36,7 +42,7 @@ public:
       return asDerived().ghostLevelImpl();
     }
 
-  /// \brief Return the number of cells in (this partition of the) grid
+    /// Return the number of cells in (this partition of the) grid
     std::uint64_t numCells () const
     {
       return asDerived().numCellsImpl();
@@ -48,7 +54,7 @@ public:
       return asDerived().numPointsImpl();
     }
 
-  /// Return a flat vector of point coordinates
+    /// \brief Return a flat vector of point coordinates
     /**
     * All coordinates are extended to 3 components and concatenated.
     * [p0_x, p0_y, p0_z, p1_x, p1_y, p1_z, ...]
@@ -61,7 +67,7 @@ public:
       return asDerived().template pointsImpl<T>();
     }
 
-  /// Return a flat vector of function values evaluated at the points.
+    /// \brief Return a flat vector of function values evaluated at the points.
     /**
     * In case of a vector valued function, flat the vector entries:
     * [fct(p0)_0, fct(p0)_1, fct(p0)_2, fct(p1)_0, ...]
@@ -76,7 +82,7 @@ public:
       return asDerived().template pointDataImpl<T>(fct);
     }
 
-  /// Return a flat vector of function values evaluated at the cells in the order of traversal.
+    /// \brief Return a flat vector of function values evaluated at the cells in the order of traversal.
     /**
     * \see pointData.
     * Note: Cells might be descibred explicitly by connectivity, offsets, and types, e.g. in
@@ -89,7 +95,7 @@ public:
       return asDerived().template cellDataImpl<T>(fct);
     }
 
-protected: // cast to derived type
+  protected: // cast to derived type
 
     Derived& asDerived ()
     {
@@ -101,7 +107,7 @@ protected: // cast to derived type
       return static_cast<const Derived&>(*this);
     }
 
-public: // default implementations
+  public: // default implementations
 
     void updateImpl ()
     {
@@ -117,9 +123,9 @@ public: // default implementations
     template <class T, class VtkFunction>
     std::vector<T> cellDataImpl (VtkFunction const& fct) const;
 
-protected:
+  protected:
     GridView gridView_;
-};
+  };
 
 } // end namespace Dune
 

dune/vtk/defaultvtkfunction.hh

@@ -25,21 +25,25 @@ namespace Dune
     using Range = std::decay_t<decltype(std::declval<F>()(std::declval<D>()))>;
 
   public:
+    /// Constructor. Stores a copy of the passed `localFct` in a local variable.
     template <class LocalFct, disableCopyMove<Self, LocalFct> = 0>
     LocalFunctionWrapper (LocalFct&& localFct)
       : localFct_(std::forward<LocalFct>(localFct))
     {}
 
+    /// Bind the LocalFunction to the Entity
     virtual void bind (Entity const& entity) override
     {
       localFct_.bind(entity);
     }
 
+    /// Unbind the LocalFunction from the Entity
     virtual void unbind () override
     {
       localFct_.unbind();
     }
 
+    /// Evaluate the LocalFunction in LocalCoordinates
     virtual double evaluate (int comp, LocalCoordinate const& xi) const override
     {
       return evaluateImpl(comp, localFct_(xi));

dune/vtk/gridcreatorinterface.hh

@@ -9,16 +9,25 @@
 
 #include <dune/vtk/forward.hh>
 
-namespace Dune {
-
-template <class G, class Derived>
-class GridCreatorInterface
+namespace Dune
 {
-public:
+
+  /// Base class for grid creators in a CRTP style.
+  /**
+   * Construct a grid from data read from VTK files.
+   *
+   * \tparam GridView   Model of Dune::GridView
+   * \tparam Derived    Implementation of a concrete GridCreator.
+   **/
+  template <class G, class Derived>
+  class GridCreatorInterface
+  {
+  public:
     using Grid = G;
     using GlobalCoordinate = typename Grid::template Codim<0>::Entity::Geometry::GlobalCoordinate;
 
-public:
+  public:
+    /// Constructor. Stores a reference to the passed GridFactory
     GridCreatorInterface (GridFactory<Grid>& factory)
       : factory_(&factory)
     {}
@@ -56,7 +65,7 @@ public:
       return MPIHelper::getCollectiveCommunication();
     }
 
-protected: // cast to derived type
+  protected: // cast to derived type
 
     Derived& asDerived ()
     {
@@ -68,7 +77,7 @@ protected: // cast to derived type
       return static_cast<const Derived&>(*this);
     }
 
-public: // default implementations
+  public: // default implementations
 
     void insertVerticesImpl (std::vector<GlobalCoordinate> const&,
                             std::vector<std::uint64_t> const&)
@@ -88,8 +97,8 @@ public: // default implementations
       /* do nothing */;
     }
 
-protected:
+  protected:
     GridFactory<Grid>* factory_;
-};
+  };
 
 } // end namespace Dune

dune/vtk/gridcreators/parallelgridcreator.hh

@@ -13,6 +13,7 @@
 
 namespace Dune
 {
+  // create a distributed grid in parallel. Currently only supported by ALUGrid
   template <class Grid>
   struct ParallelGridCreator
       : public DerivedGridCreator<ContinuousGridCreator<Grid>, ParallelGridCreator<Grid>>

dune/vtk/legacyvtkfunction.hh

@@ -18,20 +18,24 @@ namespace Dune
     using LocalCoordinate = typename Interface::LocalCoordinate;
 
   public:
+    /// Constructor. Stores a shared pointer to the passed Dune::VTKFunction
     VTKLocalFunctionWrapper (std::shared_ptr<VTKFunction<GridView> const> const& fct)
       : fct_(fct)
     {}
 
+    /// Stores a pointer to the passed entity
     virtual void bind (Entity const& entity) override
     {
       entity_ = &entity;
     }
 
+    /// Unsets the stored entity pointer
     virtual void unbind () override
     {
       entity_ = nullptr;
     }
 
+    /// Evaluate the Dune::VTKFunction in LocalCoordinates on the stored Entity
     virtual double evaluate (int comp, LocalCoordinate const& xi) const override
     {
       return fct_->evaluate(comp, *entity_, xi);

dune/vtk/pvdwriter.hh

@@ -18,8 +18,6 @@ namespace Dune
   {
     using Self = PvdWriter;
 
-    // static_assert(IsVtkWriter<VtkWriter>::value, "Writer must implement the VtkWriterInterface.");
-
   public:
     /// Constructor, creates a VtkWriter with constructor arguments forwarded
     template <class... Args, disableCopyMove<Self,Args...> = 0>
@@ -30,7 +28,7 @@ namespace Dune
       datatype_ = vtkWriter_.getDatatype();
     }
 
-    /// Write the attached data to the file
+    /// \brief Write the attached data to the file
     /**
      * Create timestep files for the data associated to the current timestep `time`.
      *
@@ -44,8 +42,8 @@ namespace Dune
     void writeTimestep (double time, std::string const& fn, Std::optional<std::string> dir = {},
                         bool writeCollection = true) const;
 
-    /// Writes collection of timesteps to .pvd file.
-    // NOTE: requires an aforging call to \ref writeTimestep
+    /// \brief Writes collection of timesteps to .pvd file.
+    // NOTE: requires an aforgoing call to \ref writeTimestep
     /**
      * \param fn  The filename of the PVD file. May contain directory and any filename extension.
      * \param dir (Ignored) Timestep files are already written and their filenames are

dune/vtk/vtkfunction.hh

@@ -35,6 +35,7 @@ namespace Dune
   constexpr int sizeOf () { return Impl::SizeImpl<std::decay_t<T>>::value; }
 
 
+  /// Wrapper class for functions allowing local evaluations.
   template <class GridView>
   class VtkFunction
   {
@@ -48,6 +49,10 @@ namespace Dune
 
   public:
     /// Constructor VtkFunction from legacy VTKFunction
+    /**
+     * \param fct   The VTKFunction to wrap
+     * \param type  The VTK datatype how to write the function values to the output [Vtk::FLOAT64]
+     **/
     VtkFunction (std::shared_ptr<VTKFunction<GridView> const> const& fct,
                  Std::optional<Vtk::DataTypes> type = {})
       : localFct_(fct)

dune/vtk/vtkreader.hh

@@ -52,15 +52,19 @@ namespace Dune
       : creator_(creator)
     {}
 
+    // disable copy and move operations
+    VtkReader(VtkReader const&) = delete;
+    VtkReader(VtkReader&&) = delete;
+    VtkReader& operator=(VtkReader const&) = delete;
+    VtkReader& operator=(VtkReader&&) = delete;
+
     /// Read the grid from file with `filename` into the GridFactory \ref factory_
+    /**
+     * \param filename  The name of the input file
+     * \param create    If `false`, only fill internal data structures, if `true`, also create the grid. [true]
+     **/
     void readFromFile (std::string const& filename, bool create = true);
 
-    /// Read the grid from and input stream into the GridFactory \ref factory_
-    void readSerialFileFromStream (std::ifstream& input, bool create = true);
-
-    /// Read the grid from and input stream into the GridFactory \ref factory_
-    void readParallelFileFromStream (std::ifstream& input, int rank, int size, bool create = true);
-
     /// Implementation of \ref FileReader interface
     static void readFactoryImpl (GridFactory<Grid>& factory, std::string const& filename)
     {
@@ -68,9 +72,29 @@ namespace Dune
       reader.readFromFile(filename);
     }
 
+    /// Advanced read methods
+    /// @{
+
+    /// Read the grid from an input stream, referring to a .vtu file, into the GridFactory \ref factory_
+    /**
+     * \param input   A STL input stream to read the VTK file from.
+     * \param create  If `false`, only fill internal data structures, if `true`, also create the grid. [true]
+     **/
+    void readSerialFileFromStream (std::ifstream& input, bool create = true);
+
+    /// Read the grid from and input stream, referring to a .pvtu file, into the GridFactory \ref factory_
+    /**
+     * \param input   A STL input stream to read the VTK file from.
+     * \param create  If `false`, only fill internal data structures, if `true`, also create the grid. [true]
+     **/
+    void readParallelFileFromStream (std::ifstream& input, int rank, int size, bool create = true);
+
     /// Construct a grid using the GridCreator
+    // NOTE: requires the internal data structures to be filled by an aforgoing call to readFromFile
     void createGrid(bool insertPieces = true);
 
+    /// @}
+
     /// Return the filenames of parallel pieces
     std::vector<std::string> const& pieces () const
     {

dune/vtk/vtktimeserieswriter.hh

@@ -67,7 +67,7 @@ namespace Dune
                         bool writeCollection = true) const;
 
     /// Writes all timesteps to single timeseries file.
-    // NOTE: requires an aforging call to \ref writeTimestep
+    // NOTE: requires an aforgoing call to \ref writeTimestep
     /**
      * Create a timeseries file with all timesteps written by \ref writeTimestep.
      *

dune/vtk/vtkwriter.hh

@@ -33,7 +33,7 @@ namespace Dune
    * are provided, like YaspGrid and GeometrGrid.
    *
    * Note: Uses the default data-collector. If you want to choose a special data-collector, use
-   * the concrete write Implementation instead.
+   * the concrete writer Implementation instead. \see VtkWriterInterface
    **/
   template <class GridView>
   using VtkWriter = typename Impl::VtkWriterImpl<GridView, typename GridView::Grid>::type;

dune/vtk/vtkwriterinterface.hh

@@ -14,6 +14,10 @@
 namespace Dune
 {
   /// Interface for file writers for the Vtk XML file formats
+  /**
+   * \tparam GridView       Model of Dune::GridView
+   * \tparam DataCollector  Model of \ref DataCollectorInterface
+   **/
   template <class GridView, class DataCollector>
   class VtkWriterInterface
       : public FileWriter
@@ -34,7 +38,16 @@ namespace Dune
     };
 
   public:
-    /// Constructor, stores the gridView
+    /// \brief Constructor, passes the gridView to the DataCollector
+    /**
+     * Creates a new VtkWriterInterface for the provided GridView. Initializes a
+     * DataCollector that is used to collect point coordinates, cell connectivity and
+     * data values.
+     *
+     * \param gridView  Implementation of Dune::GridView
+     * \param format    Format of the VTK file, either Vtk::BINARY, Vtk::ASCII, or Vtk::COMPRESSED
+     * \param datatype  Output datatype used for coordinates and other global floating point values
+     **/
     VtkWriterInterface (GridView const& gridView,
                         Vtk::FormatTypes format = Vtk::BINARY,
                         Vtk::DataTypes datatype = Vtk::FLOAT32)
@@ -50,14 +63,21 @@ namespace Dune
 #endif
     }
 
-    /// Write the attached data to the file
+    /// \brief Write the attached data to the file
     /**
      * \param fn   Filename of the VTK file. May contain a directory and any file extension.
-     * \param dir  The optional parameter specifies the directory of the partition files.
+     * \param dir  The optional parameter specifies the directory of the partition files for parallel writes.
      **/
     virtual void write (std::string const& fn, Std::optional<std::string> dir = {}) const override;
 
-    /// Attach point data to the writer, \see VtkFunction for possible arguments
+    /// \brief Attach point data to the writer
+    /**
+     * Attach a global function to the writer that will be evaluated at grid points
+     * (vertices and higher order points). The global function must be
+     * assignable to the function wrapper \ref VtkFunction. Additional argument
+     * for output datatype and number of components can be bassed. See \ref VtkFunction
+     * Constructor for possible arguments.
+     **/
     template <class Function, class... Args>
     VtkWriterInterface& addPointData (Function const& fct, Args&&... args)
     {
@@ -65,7 +85,13 @@ namespace Dune
       return *this;
     }
 
-    /// Attach cell data to the writer, \see VtkFunction for possible arguments
+    /// \brief Attach cell data to the writer
+    /**
+     * Attach a global function to the writer that will be evaluated at cell centers.
+     * The global function must be assignable to the function wrapper \ref VtkFunction.
+     * Additional argument for output datatype and number of components can be bassed.
+     * See \ref VtkFunction Constructor for possible arguments.
+     **/
     template <class Function, class... Args>
     VtkWriterInterface& addCellData (Function const& fct, Args&&... args)
     {
@@ -77,7 +103,7 @@ namespace Dune
     /// Write a serial VTK file in Unstructured format
     virtual void writeSerialFile (std::ofstream& out) const = 0;
 
-    /// Write a parallel VTK file `pfilename.pvtu` in Unstructured format,
+    /// Write a parallel VTK file `pfilename.pvtx` in XML format,
     /// with `size` the number of pieces and serial files given by `pfilename_p[i].vtu`
     /// for [i] in [0,...,size).
     virtual void writeParallelFile (std::ofstream& out, std::string const& pfilename, int size) const = 0;
@@ -90,19 +116,19 @@ namespace Dune
 
   protected:
     // Write the point or cell values given by the grid function `fct` to the
-    // output stream `out`. In case of binary format, stores the streampos of XML
-    // attributes "offset" in the vector `offsets`.
+    // output stream `out`. In case of binary format, append the streampos of XML
+    // attributes "offset" to the vector `offsets`.
     void writeData (std::ofstream& out,
                     std::vector<pos_type>& offsets,
                     VtkFunction const& fct,
                     PositionTypes type,
                     Std::optional<std::size_t> timestep = {}) const;
 
-    // Write points-data and cell-data in raw/compressed format to output stream
+    // Write point-data and cell-data in raw/compressed format to output stream
     void writeDataAppended (std::ofstream& out, std::vector<std::uint64_t>& blocks) const;
 
     // Write the coordinates of the vertices to the output stream `out`. In case
-    // of binary format, stores the streampos of XML attributes "offset" in the
+    // of binary format, appends the streampos of XML attributes "offset" to the
     // vector `offsets`.
     void writePoints (std::ofstream& out,
                       std::vector<pos_type>& offsets,
@@ -116,9 +142,12 @@ namespace Dune
     template <class T>
     std::uint64_t writeValuesAppended (std::ofstream& out, std::vector<T> const& values) const;
 
+    // Write the `values` in a space and newline separated list of ascii representations.
+    // The precision is controlled by the datatype and numerical_limits::digits10.
     template <class T>
     void writeValuesAscii (std::ofstream& out, std::vector<T> const& values) const;
 
+    // Write the XML file header of a VTK file `<VTKFile ...>`
     void writeHeader (std::ofstream& out, std::string const& type) const;
 
     /// Return PointData/CellData attributes for the name of the first scalar/vector/tensor DataArray
@@ -137,16 +166,19 @@ namespace Dune
       return fileExtension();
     }
 
+    // Returns the VTK file format initialized in the constructor
     Vtk::FormatTypes getFormat () const
     {
       return format_;
     }
 
+    // Returns the global datatype used for coordinates and other global float values
     Vtk::DataTypes getDatatype () const
     {
       return datatype_;
     }
 
+    // Return the global MPI communicator.
     auto comm () const
     {
       return MPIHelper::getCollectiveCommunication();