From: Wolfgang Bangerth Date: Sun, 16 Aug 2015 23:05:05 +0000 (-0500) Subject: Properly document get_data() and friends. X-Git-Tag: v8.4.0-rc2~591^2~1 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6f9b97a1f4c2bf83fd2941689d115a0d718ad4e8;p=dealii.git Properly document get_data() and friends. 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. --- diff --git a/include/deal.II/fe/mapping.h b/include/deal.II/fe/mapping.h index 2f1ecddcdb..c93002f4c6 100644 --- a/include/deal.II/fe/mapping.h +++ b/include/deal.II/fe/mapping.h @@ -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 derived + * 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 &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 derived + * 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 &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 derived + * 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 * @{ */ diff --git a/include/deal.II/fe/mapping_cartesian.h b/include/deal.II/fe/mapping_cartesian.h index 1ec35ff102..25044e317e 100644 --- a/include/deal.II/fe/mapping_cartesian.h +++ b/include/deal.II/fe/mapping_cartesian.h @@ -54,16 +54,19 @@ template class MappingCartesian : public Mapping { public: + // documentation can be found in Mapping::get_data() virtual typename Mapping::InternalDataBase * get_data (const UpdateFlags, const Quadrature &quadrature) const; + // documentation can be found in Mapping::get_face_data() virtual typename Mapping::InternalDataBase * get_face_data (const UpdateFlags flags, const Quadrature& quadrature) const; + // documentation can be found in Mapping::get_subface_data() virtual typename Mapping::InternalDataBase * get_subface_data (const UpdateFlags flags, @@ -224,10 +227,7 @@ protected: std::vector > &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; diff --git a/include/deal.II/fe/mapping_fe_field.h b/include/deal.II/fe/mapping_fe_field.h index 2e64529b34..3a65b0ff35 100644 --- a/include/deal.II/fe/mapping_fe_field.h +++ b/include/deal.II/fe/mapping_fe_field.h @@ -519,10 +519,7 @@ private: compute_shapes_virtual (const std::vector > &unit_points, typename MappingFEField::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 &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::InternalDataBase * get_face_data (const UpdateFlags flags, const Quadrature& 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::InternalDataBase * get_subface_data (const UpdateFlags flags, diff --git a/include/deal.II/fe/mapping_q.h b/include/deal.II/fe/mapping_q.h index c49e8fc4ca..e0261146c5 100644 --- a/include/deal.II/fe/mapping_q.h +++ b/include/deal.II/fe/mapping_q.h @@ -293,27 +293,19 @@ private: const TriaIterator &iter, std::vector > &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 &quadrature) const; + // documentation can be found in Mapping::get_face_data() virtual typename Mapping::InternalDataBase * get_face_data (const UpdateFlags flags, const Quadrature& quadrature) const; + // documentation can be found in Mapping::get_subface_data() virtual typename Mapping::InternalDataBase * get_subface_data (const UpdateFlags flags, diff --git a/include/deal.II/fe/mapping_q1.h b/include/deal.II/fe/mapping_q1.h index 0ac0ab8197..cc4dd0358a 100644 --- a/include/deal.II/fe/mapping_q1.h +++ b/include/deal.II/fe/mapping_q1.h @@ -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 &quadrature) const; + // documentation can be found in Mapping::get_face_data() virtual typename Mapping::InternalDataBase * get_face_data (const UpdateFlags flags, const Quadrature& quadrature) const; + // documentation can be found in Mapping::get_subface_data() virtual typename Mapping::InternalDataBase * get_subface_data (const UpdateFlags flags,