Merge branch 'issue/document_gradtransfer' into 'develop'

Added some documentation to the GridTransferInterface and GridTransfer

See merge request spraetor/dune-amdis!101

src/amdis/GridTransfer.hpp

@@ -18,10 +18,19 @@ namespace AMDiS
   public:
     virtual ~GridTransferInterface() = default;
 
+    /// Attach a data container to the grid transfer, that gets interpolated during grid change
     virtual void attach(DOFVectorInterface*) = 0;
+
+    /// Remove a data constainer from the grid transfer. Throws a warning if container not found.
     virtual void detach(DOFVectorInterface*) = 0;
+
+    /// Prepare the grid and the data for the adaption
     virtual bool preAdapt() = 0;
+
+    /// Do the grid adaption
     virtual bool adapt() = 0;
+
+    // Perform data adaption to the new grid
     virtual void postAdapt() = 0;
   };
 
@@ -34,22 +43,33 @@ namespace AMDiS
     using Self = GridTransfer;
 
   public:
+    /// Bind a (mutable) grid to this GridTransfer. Must be called before any xxxAdapt() method.
+    // [[ensures: bound()]]
     void bind(Grid& grid)
     {
       grid_ = &grid;
     }
 
+    /// Release the grid from this GridTransfer
+    // [[ensures: not bound()]]
     void unbind()
     {
       grid_ = nullptr;
     }
 
-    /// Attach a data container to the grid transfer, that gets interpolated during grid change
+    /// Returns whether this GridTransfer is bound to a grid.
+    bool bound() const
+    {
+      return grid_ != nullptr;
+    }
+
+    /// Implements \ref GridTransferInterface::attach
     void attach(DOFVectorInterface* vec) override
     {
       data_.push_back(vec);
     }
 
+    /// Implements \ref GridTransferInterface::detach
     void detach(DOFVectorInterface* vec) override
     {
       auto it = std::find(data_.begin(), data_.end(), vec);
@@ -59,28 +79,31 @@ namespace AMDiS
         warning("DOFVector to detach not found");
     }
 
-    /// Prepare the grid and the data for the adaption
+    /// Implements \ref GridTransferInterface::preAdapt
+    // [[expects: bound()]]
     bool preAdapt() override
     {
-      assert(grid_ != nullptr);
-      mightCoarsen_ = grid_->preAdapt(); // any element might be coarsened in adapt()
+      assert(bound());
+      mightCoarsen_ = grid_->preAdapt();
       for (auto* vec : this->data_)
         vec->preAdapt(mightCoarsen_);
       return mightCoarsen_;
     }
 
-    /// do the grid adaption
+    /// Implements \ref GridTransferInterface::adapt
+    // [[expects: bound()]]
     bool adapt() override
     {
-      assert(grid_ != nullptr);
-      refined_ = grid_->adapt(); // returns true if a least one entity was refined
+      assert(bound());
+      refined_ = grid_->adapt();
       return refined_;
     }
 
-    // Perform data adaption to the new grid
+    /// Implements \ref GridTransferInterface::postAdapt
+    // [[expects: bound()]]
     void postAdapt() override
     {
-      assert(grid_ != nullptr);
+      assert(bound());
       if (mightCoarsen_ || refined_) {
         for (auto* vec : this->data_)
           vec->postAdapt(refined_);
@@ -96,13 +119,19 @@ namespace AMDiS
     }
 
   private:
+    /// A grid this GridTransfer is bound to in \ref bind()
     Grid* grid_ = nullptr;
+
+    /// A list of data containers handled during grid adaption
     std::list<DOFVectorInterface*> data_;
+
+    /// Flag set during \ref preAdapt(), indicating whether any element might be coarsened in \ref adapt()
     bool mightCoarsen_ = false;
+
+    /// Flag set during \ref adapt() indicating that at least one entity was refined
     bool refined_ = false;
 
-    /// This index is incremented every time the grid is changed, e.g. by
-    /// refinement or coarsening.
+    /// This index is incremented every time the grid is changed, e.g. by refinement or coarsening.
     unsigned long changeIndex_ = 0;
   };