]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Properly document get_data() and friends.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Sun, 16 Aug 2015 23:05:05 +0000 (18:05 -0500)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Tue, 18 Aug 2015 11:33:18 +0000 (06:33 -0500)
Also remove the documentation from these functions in derived classes
as doxygen properly copies the documentation from the corresponding
functions in the base class. This makes sure we only have to document
in one place and avoids things getting out of synch.

include/deal.II/fe/mapping.h
include/deal.II/fe/mapping_cartesian.h
include/deal.II/fe/mapping_fe_field.h
include/deal.II/fe/mapping_q.h
include/deal.II/fe/mapping_q1.h

index 2f1ecddcdbb9ba33faad0eca84ec63f617dbbb96..c93002f4c621f6f008e0db34aa62fce45e5e39b8 100644 (file)
@@ -554,9 +554,50 @@ protected:
   requires_update_flags (const UpdateFlags update_flags) const = 0;
 
   /**
-   * Prepare internal data structures and fill in values independent of the
-   * cell. See the documentation of Mapping::InternalDataBase for more
-   * information on the purpose of this function.
+   * Create and return a pointer to an object into which mappings can
+   * store data that only needs to be computed once but that can then
+   * be used whenever the mapping is applied to a concrete cell (e.g.,
+   * in the various transform() functions, as well as in the
+   * fill_fe_values(), fill_fe_face_values() and fill_fe_subface_values()
+   * that form the interface of mappings with the FEValues class).
+   *
+   * Derived classes will return pointers to objects of a type
+   * derived from Mapping::InternalDataBase (see there for more information)
+   * and may pre-compute some information already (in accordance with what will
+   * be asked of the mapping in the future, as specified by the update
+   * flags) and for the given quadrature object. Subsequent calls to
+   * transform() or fill_fe_values() and friends will then receive back the
+   * object created here (with the same set of update flags and for the
+   * same quadrature object). Derived classes can therefore pre-compute
+   * some information in their get_data() function and store it in
+   * the internal data object.
+   *
+   * The mapping classes do not keep track of the objects created by
+   * this function. Ownership will therefore rest with the caller.
+   *
+   * @param update_flags A set of flags that define what is expected of
+   *   the mapping class in future calls to transform() or the
+   *   fill_fe_values() group of functions. This set of flags may
+   *   contain flags that mappings do not know how to deal with
+   *   (e.g., for information that is in fact computed by the
+   *   finite element classes, such as UpdateFlags::update_values).
+   *   Derived classes will need to store these flags, or at least that
+   *   subset of flags that will require the mapping to perform any
+   *   actions in fill_fe_values(), in InternalDataBase::update_each.
+   * @param quadrature The quadrature object for which mapping
+   *   information will have to be computed. This includes the
+   *   locations and weights of quadrature points.
+   * @return A pointer to a newly created object of type
+   *   InternalDataBase (or a derived class). Ownership of this
+   *   object passes to the calling function.
+   *
+   * @note C++ allows that virtual functions in derived classes
+   *   may return pointers to objects not of type InternalDataBase
+   *   but in fact pointers to objects of classes <i>derived</i>
+   *   from InternalDataBase. (This feature is called "covariant return
+   *   types".) This is useful in some contexts where the calling
+   *   is within the derived class and will immediately make use
+   *   of the returned object, knowing its real (derived) type.
    */
   virtual
   InternalDataBase *
@@ -564,10 +605,34 @@ protected:
             const Quadrature<dim> &quadrature) const = 0;
 
   /**
-   * Prepare internal data structure for transformation of faces and fill in
-   * values independent of the cell. See the documentation of
-   * Mapping::InternalDataBase for more
-   * information on the purpose of this function.
+   * Like get_data(), but in preparation for later calls to
+   * transform() or fill_fe_face_values() that will need
+   * information about mappings from the reference face to a
+   * face of a concrete cell.
+   *
+   * @param update_flags A set of flags that define what is expected of
+   *   the mapping class in future calls to transform() or the
+   *   fill_fe_values() group of functions. This set of flags may
+   *   contain flags that mappings do not know how to deal with
+   *   (e.g., for information that is in fact computed by the
+   *   finite element classes, such as UpdateFlags::update_values).
+   *   Derived classes will need to store these flags, or at least that
+   *   subset of flags that will require the mapping to perform any
+   *   actions in fill_fe_values(), in InternalDataBase::update_each.
+   * @param quadrature The quadrature object for which mapping
+   *   information will have to be computed. This includes the
+   *   locations and weights of quadrature points.
+   * @return A pointer to a newly created object of type
+   *   InternalDataBase (or a derived class). Ownership of this
+   *   object passes to the calling function.
+   *
+   * @note C++ allows that virtual functions in derived classes
+   *   may return pointers to objects not of type InternalDataBase
+   *   but in fact pointers to objects of classes <i>derived</i>
+   *   from InternalDataBase. (This feature is called "covariant return
+   *   types".) This is useful in some contexts where the calling
+   *   is within the derived class and will immediately make use
+   *   of the returned object, knowing its real (derived) type.
    */
   virtual
   InternalDataBase *
@@ -575,10 +640,34 @@ protected:
                  const Quadrature<dim-1> &quadrature) const = 0;
 
   /**
-   * Prepare internal data structure for transformation of children of faces
-   * and fill in values independent of the cell. See the documentation
-   * of Mapping::InternalDataBase for more
-   * information on the purpose of this function.
+   * Like get_data() and get_face_data(), but in preparation for later calls to
+   * transform() or fill_fe_subface_values() that will need
+   * information about mappings from the reference face to a
+   * child of a face (i.e., subface) of a concrete cell.
+   *
+   * @param update_flags A set of flags that define what is expected of
+   *   the mapping class in future calls to transform() or the
+   *   fill_fe_values() group of functions. This set of flags may
+   *   contain flags that mappings do not know how to deal with
+   *   (e.g., for information that is in fact computed by the
+   *   finite element classes, such as UpdateFlags::update_values).
+   *   Derived classes will need to store these flags, or at least that
+   *   subset of flags that will require the mapping to perform any
+   *   actions in fill_fe_values(), in InternalDataBase::update_each.
+   * @param quadrature The quadrature object for which mapping
+   *   information will have to be computed. This includes the
+   *   locations and weights of quadrature points.
+   * @return A pointer to a newly created object of type
+   *   InternalDataBase (or a derived class). Ownership of this
+   *   object passes to the calling function.
+   *
+   * @note C++ allows that virtual functions in derived classes
+   *   may return pointers to objects not of type InternalDataBase
+   *   but in fact pointers to objects of classes <i>derived</i>
+   *   from InternalDataBase. (This feature is called "covariant return
+   *   types".) This is useful in some contexts where the calling
+   *   is within the derived class and will immediately make use
+   *   of the returned object, knowing its real (derived) type.
    */
   virtual
   InternalDataBase *
@@ -749,7 +838,7 @@ protected:
 public:
 
   /**
-   * @name Functions usable by finite element fields to map points and tensors
+   * @name Functions to transform tensors from reference to real coordinates
    * @{
    */
 
index 1ec35ff102e903dff800afb743097b120b98c175..25044e317e229f2cb71602dbff47a5b76a0cd2e9 100644 (file)
@@ -54,16 +54,19 @@ template <int dim, int spacedim=dim>
 class MappingCartesian : public Mapping<dim,spacedim>
 {
 public:
+  // documentation can be found in Mapping::get_data()
   virtual
   typename Mapping<dim, spacedim>::InternalDataBase *
   get_data (const UpdateFlags,
             const Quadrature<dim> &quadrature) const;
 
+  // documentation can be found in Mapping::get_face_data()
   virtual
   typename Mapping<dim, spacedim>::InternalDataBase *
   get_face_data (const UpdateFlags flags,
                  const Quadrature<dim-1>& quadrature) const;
 
+  // documentation can be found in Mapping::get_subface_data()
   virtual
   typename Mapping<dim, spacedim>::InternalDataBase *
   get_subface_data (const UpdateFlags flags,
@@ -224,10 +227,7 @@ protected:
                      std::vector<Point<dim> > &normal_vectors) const;
 
 private:
-  /**
-   * Implementation of the corresponding function in the base class,
-   * Mapping::requires_update_flags(). See there for more information.
-   */
+  // documentation can be found in Mapping::requires_update_flags()
   virtual
   UpdateFlags
   requires_update_flags (const UpdateFlags update_flags) const;
index 2e64529b345037726c60a3fc278299ee2f840518..3a65b0ff35910447bdab1e05cc7872a6565290c3 100644 (file)
@@ -519,10 +519,7 @@ private:
   compute_shapes_virtual (const std::vector<Point<dim> > &unit_points,
                           typename MappingFEField<dim, spacedim>::InternalData &data) const;
 
-  /**
-   * Implementation of the corresponding function in the base class,
-   * Mapping::requires_update_flags(). See there for more information.
-   */
+  // documentation can be found in Mapping::requires_update_flags()
   virtual
   UpdateFlags
   requires_update_flags (const UpdateFlags update_flags) const;
@@ -547,28 +544,19 @@ private:
                      const unsigned int     n_original_q_points,
                      InternalData           &data) const;
 
-  /**
-   * Reimplemented from Mapping. See the documentation of the base class for
-   * detailed information.
-   */
+  // documentation can be found in Mapping::get_data()
   virtual
   InternalData *
   get_data (const UpdateFlags,
             const Quadrature<dim> &quadrature) const;
 
-  /**
-   * Reimplemented from Mapping. See the documentation of the base class for
-   * detailed information.
-   */
+  // documentation can be found in Mapping::get_face_data()
   virtual
   typename Mapping<dim,spacedim>::InternalDataBase *
   get_face_data (const UpdateFlags flags,
                  const Quadrature<dim-1>& quadrature) const;
 
-  /**
-   * Reimplemented from Mapping. See the documentation of the base class for
-   * detailed information.
-   */
+  // documentation can be found in Mapping::get_subface_data()
   virtual
   typename Mapping<dim,spacedim>::InternalDataBase *
   get_subface_data (const UpdateFlags flags,
index c49e8fc4ca1fb8189dfea81b17349d1719362d85..e0261146c5b3ccd1bf38c7aceb11d9113128ffcb 100644 (file)
@@ -293,27 +293,19 @@ private:
                                          const TriaIterator &iter,
                                          std::vector<Point<spacedim> > &points) const;
 
-
-  /**
-   * Implementation of the Mapping::get_data() interface.
-   *
-   * As allowed by C++ (using a feature called "covariant return
-   * types"), this function returns a pointer to a
-   * MappingQ::InternalData object since these objects are
-   * derived from the Mapping::InternalDataBase class, pointers to
-   * which are returned by the Mapping::get_data() function. This
-   * makes some uses of this function simpler.
-   */
+  // documentation can be found in Mapping::get_data()
   virtual
   InternalData *
   get_data (const UpdateFlags,
             const Quadrature<dim> &quadrature) const;
 
+  // documentation can be found in Mapping::get_face_data()
   virtual
   typename Mapping<dim,spacedim>::InternalDataBase *
   get_face_data (const UpdateFlags flags,
                  const Quadrature<dim-1>& quadrature) const;
 
+  // documentation can be found in Mapping::get_subface_data()
   virtual
   typename Mapping<dim,spacedim>::InternalDataBase *
   get_subface_data (const UpdateFlags flags,
index 0ac0ab8197fa3622643fd3a015decf01f7e89fd1..cc4dd0358a98c2911c8cb781defd5d87923c030c 100644 (file)
@@ -177,7 +177,8 @@ public:
    * Storage for internal data of d-linear mappings. See Mapping::InternalDataBase
    * for an extensive description.
    *
-   * This includes data that is computed once when the object is created
+   * For the current class MappingQ1, the InternalData class store
+   * data that is computed once when the object is created
    * (in get_data()) as well as data the class wants to store from between
    * the call to fill_fe_values(), fill_fe_face_values(), or
    * fill_fe_subface_values() until possible later calls from the finite
@@ -496,34 +497,24 @@ protected:
 
 private:
 
-  /**
-   * Implementation of the corresponding function in the base class,
-   * Mapping::requires_update_flags(). See there for more information.
-   */
+  // documentation can be found in Mapping::requires_update_flags()
   virtual
   UpdateFlags
   requires_update_flags (const UpdateFlags update_flags) const;
 
-  /**
-   * Implementation of the Mapping::get_data() interface.
-   *
-   * As allowed by C++ (using a feature called "covariant return
-   * types"), this function returns a pointer to a
-   * MappingQ1::InternalData object since these objects are
-   * derived from the Mapping::InternalDataBase class, pointers to
-   * which are returned by the Mapping::get_data() function. This
-   * makes some uses of this function simpler.
-   */
+  // documentation can be found in Mapping::get_data()
   virtual
   InternalData *
   get_data (const UpdateFlags,
             const Quadrature<dim> &quadrature) const;
 
+  // documentation can be found in Mapping::get_face_data()
   virtual
   typename Mapping<dim,spacedim>::InternalDataBase *
   get_face_data (const UpdateFlags flags,
                  const Quadrature<dim-1>& quadrature) const;
 
+  // documentation can be found in Mapping::get_subface_data()
   virtual
   typename Mapping<dim,spacedim>::InternalDataBase *
   get_subface_data (const UpdateFlags flags,

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.