From: Wolfgang Bangerth Date: Tue, 17 Nov 2020 01:00:45 +0000 (-0700) Subject: Better document a bunch of functions. X-Git-Tag: v9.3.0-rc1~895^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=80c060b8c1b730adc690b7892e965c208d999759;p=dealii.git Better document a bunch of functions. --- diff --git a/include/deal.II/fe/fe_values.h b/include/deal.II/fe/fe_values.h index c0ad804b59..41360861dc 100644 --- a/include/deal.II/fe/fe_values.h +++ b/include/deal.II/fe/fe_values.h @@ -351,26 +351,38 @@ namespace FEValuesViews &values) const; /** - * Same as above, but using a vector of local degree-of-freedom values. - * - * The @p dof_values vector must have a length equal to number of DoFs on - * a cell, and each entry @p dof_values[i] is the value of the local DoF - * @p i. The fundamental prerequisite for the @p InputVector is that it must - * be possible to create an ArrayView from it; this is satisfied by the - * @p std::vector class. - * - * The DoF values typically would be obtained in the following way: - * @code - * Vector local_dof_values(cell->get_fe().n_dofs_per_cell()); - * cell->get_dof_values(solution, local_dof_values); - * @endcode - * or, for a generic @p Number type, + * Same as above, but using a vector of local degree-of-freedom values. In + * other words, instead of extracting the nodal values of the degrees of + * freedom located on the current cell from a global vector associated with + * a DoFHandler object (as the function above does), this function instead + * takes these local nodal values through its first argument. A typical + * way to obtain such a vector is by calling code such as * @code - * std::vector local_dof_values(cell->get_fe().n_dofs_per_cell()); - * cell->get_dof_values(solution, - * local_dof_values.begin(), - * local_dof_values.end()); + * cell->get_dof_values (dof_values, local_dof_values); * @endcode + * (See DoFCellAccessor::get_dof_values() for more information on this + * function.) The point of the current function is then that one could + * modify these local values first, for example by applying a limiter + * or by ensuring that all nodal values are positive, before evaluating + * the finite element field that corresponds to these local values on the + * current cell. Another application is where one wants to postprocess + * the solution on a cell into a different finite element space on every + * cell, without actually creating a corresponding DoFHandler -- in that + * case, all one would compute is a local representation of that + * postprocessed function, characterized by its nodal values; this function + * then allows the evaluation of that representation at quadrature points. + * + * @param[in] dof_values A vector of local nodal values. This vector must + * have a length equal to number of DoFs on the current cell, and must + * be ordered in the same order as degrees of freedom are numbered on + * the reference cell. + * + * @param[out] values A vector of values of the given finite element field, + * at the quadrature points on the current object. + * + * @tparam InputVector The @p InputVector type must allow creation + * of an ArrayView object from it; this is satisfied by the + * `std::vector` class, among others. */ template void @@ -406,7 +418,10 @@ namespace FEValuesViews &gradients) const; /** - * @copydoc FEValuesViews::Scalar::get_function_values_from_local_dof_values() + * This function relates to get_function_gradients() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -442,7 +457,10 @@ namespace FEValuesViews &hessians) const; /** - * @copydoc FEValuesViews::Scalar::get_function_values_from_local_dof_values() + * This function relates to get_function_hessians() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -480,7 +498,10 @@ namespace FEValuesViews &laplacians) const; /** - * @copydoc FEValuesViews::Scalar::get_function_values_from_local_dof_values() + * This function relates to get_function_laplacians() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -518,7 +539,10 @@ namespace FEValuesViews &third_derivatives) const; /** - * @copydoc FEValuesViews::Scalar::get_function_values_from_local_dof_values() + * This function relates to get_function_third_derivatives() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -919,26 +943,38 @@ namespace FEValuesViews &values) const; /** - * Same as above, but using a vector of local degree-of-freedom values. - * - * The @p dof_values vector must have a length equal to number of DoFs on - * a cell, and each entry @p dof_values[i] is the value of the local DoF - * @p i. The fundamental prerequisite for the @p InputVector is that it must - * be possible to create an ArrayView from it; this is satisfied by the - * @p std::vector class. - * - * The DoF values typically would be obtained in the following way: - * @code - * Vector local_dof_values(cell->get_fe().n_dofs_per_cell()); - * cell->get_dof_values(solution, local_dof_values); - * @endcode - * or, for a generic @p Number type, + * Same as above, but using a vector of local degree-of-freedom values. In + * other words, instead of extracting the nodal values of the degrees of + * freedom located on the current cell from a global vector associated with + * a DoFHandler object (as the function above does), this function instead + * takes these local nodal values through its first argument. A typical + * way to obtain such a vector is by calling code such as * @code - * std::vector local_dof_values(cell->get_fe().n_dofs_per_cell()); - * cell->get_dof_values(solution, - * local_dof_values.begin(), - * local_dof_values.end()); + * cell->get_dof_values (dof_values, local_dof_values); * @endcode + * (See DoFCellAccessor::get_dof_values() for more information on this + * function.) The point of the current function is then that one could + * modify these local values first, for example by applying a limiter + * or by ensuring that all nodal values are positive, before evaluating + * the finite element field that corresponds to these local values on the + * current cell. Another application is where one wants to postprocess + * the solution on a cell into a different finite element space on every + * cell, without actually creating a corresponding DoFHandler -- in that + * case, all one would compute is a local representation of that + * postprocessed function, characterized by its nodal values; this function + * then allows the evaluation of that representation at quadrature points. + * + * @param[in] dof_values A vector of local nodal values. This vector must + * have a length equal to number of DoFs on the current cell, and must + * be ordered in the same order as degrees of freedom are numbered on + * the reference cell. + * + * @param[out] values A vector of values of the given finite element field, + * at the quadrature points on the current object. + * + * @tparam InputVector The @p InputVector type must allow creation + * of an ArrayView object from it; this is satisfied by the + * `std::vector` class, among others. */ template void @@ -974,7 +1010,10 @@ namespace FEValuesViews &gradients) const; /** - * @copydoc FEValuesViews::Vector::get_function_values_from_local_dof_values() + * This function relates to get_function_gradients() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1016,7 +1055,10 @@ namespace FEValuesViews &symmetric_gradients) const; /** - * @copydoc FEValuesViews::Vector::get_function_values_from_local_dof_values() + * This function relates to get_function_symmetric_gradients() in the same + * way as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1052,7 +1094,10 @@ namespace FEValuesViews &divergences) const; /** - * @copydoc FEValuesViews::Vector::get_function_values_from_local_dof_values() + * This function relates to get_function_divergences() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1089,7 +1134,10 @@ namespace FEValuesViews &curls) const; /** - * @copydoc FEValuesViews::Vector::get_function_values_from_local_dof_values() + * This function relates to get_function_curls() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1125,7 +1173,10 @@ namespace FEValuesViews &hessians) const; /** - * @copydoc FEValuesViews::Vector::get_function_values_from_local_dof_values() + * This function relates to get_function_hessians() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1162,7 +1213,10 @@ namespace FEValuesViews &laplacians) const; /** - * @copydoc FEValuesViews::Vector::get_function_values_from_local_dof_values() + * This function relates to get_function_laplacians() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1199,7 +1253,10 @@ namespace FEValuesViews &third_derivatives) const; /** - * @copydoc FEValuesViews::Vector::get_function_values_from_local_dof_values() + * This function relates to get_function_third_derivatives() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1430,26 +1487,38 @@ namespace FEValuesViews &values) const; /** - * Same as above, but using a vector of local degree-of-freedom values. - * - * The @p dof_values vector must have a length equal to number of DoFs on - * a cell, and each entry @p dof_values[i] is the value of the local DoF - * @p i. The fundamental prerequisite for the @p InputVector is that it must - * be possible to create an ArrayView from it; this is satisfied by the - * @p std::vector class. - * - * The DoF values typically would be obtained in the following way: - * @code - * Vector local_dof_values(cell->get_fe().n_dofs_per_cell()); - * cell->get_dof_values(solution, local_dof_values); - * @endcode - * or, for a generic @p Number type, + * Same as above, but using a vector of local degree-of-freedom values. In + * other words, instead of extracting the nodal values of the degrees of + * freedom located on the current cell from a global vector associated with + * a DoFHandler object (as the function above does), this function instead + * takes these local nodal values through its first argument. A typical + * way to obtain such a vector is by calling code such as * @code - * std::vector local_dof_values(cell->get_fe().n_dofs_per_cell()); - * cell->get_dof_values(solution, - * local_dof_values.begin(), - * local_dof_values.end()); + * cell->get_dof_values (dof_values, local_dof_values); * @endcode + * (See DoFCellAccessor::get_dof_values() for more information on this + * function.) The point of the current function is then that one could + * modify these local values first, for example by applying a limiter + * or by ensuring that all nodal values are positive, before evaluating + * the finite element field that corresponds to these local values on the + * current cell. Another application is where one wants to postprocess + * the solution on a cell into a different finite element space on every + * cell, without actually creating a corresponding DoFHandler -- in that + * case, all one would compute is a local representation of that + * postprocessed function, characterized by its nodal values; this function + * then allows the evaluation of that representation at quadrature points. + * + * @param[in] dof_values A vector of local nodal values. This vector must + * have a length equal to number of DoFs on the current cell, and must + * be ordered in the same order as degrees of freedom are numbered on + * the reference cell. + * + * @param[out] values A vector of values of the given finite element field, + * at the quadrature points on the current object. + * + * @tparam InputVector The @p InputVector type must allow creation + * of an ArrayView object from it; this is satisfied by the + * `std::vector` class, among others. */ template void @@ -1489,7 +1558,10 @@ namespace FEValuesViews &divergences) const; /** - * @copydoc FEValuesViews::SymmetricTensor<2,dim,spacedim>::get_function_values_from_local_dof_values() + * This function relates to get_function_divergences() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1740,26 +1812,38 @@ namespace FEValuesViews &values) const; /** - * Same as above, but using a vector of local degree-of-freedom values. - * - * The @p dof_values vector must have a length equal to number of DoFs on - * a cell, and each entry @p dof_values[i] is the value of the local DoF - * @p i. The fundamental prerequisite for the @p InputVector is that it must - * be possible to create an ArrayView from it; this is satisfied by the - * @p std::vector class. - * - * The DoF values typically would be obtained in the following way: - * @code - * Vector local_dof_values(cell->get_fe().n_dofs_per_cell()); - * cell->get_dof_values(solution, local_dof_values); - * @endcode - * or, for a generic @p Number type, + * Same as above, but using a vector of local degree-of-freedom values. In + * other words, instead of extracting the nodal values of the degrees of + * freedom located on the current cell from a global vector associated with + * a DoFHandler object (as the function above does), this function instead + * takes these local nodal values through its first argument. A typical + * way to obtain such a vector is by calling code such as * @code - * std::vector local_dof_values(cell->get_fe().n_dofs_per_cell()); - * cell->get_dof_values(solution, - * local_dof_values.begin(), - * local_dof_values.end()); + * cell->get_dof_values (dof_values, local_dof_values); * @endcode + * (See DoFCellAccessor::get_dof_values() for more information on this + * function.) The point of the current function is then that one could + * modify these local values first, for example by applying a limiter + * or by ensuring that all nodal values are positive, before evaluating + * the finite element field that corresponds to these local values on the + * current cell. Another application is where one wants to postprocess + * the solution on a cell into a different finite element space on every + * cell, without actually creating a corresponding DoFHandler -- in that + * case, all one would compute is a local representation of that + * postprocessed function, characterized by its nodal values; this function + * then allows the evaluation of that representation at quadrature points. + * + * @param[in] dof_values A vector of local nodal values. This vector must + * have a length equal to number of DoFs on the current cell, and must + * be ordered in the same order as degrees of freedom are numbered on + * the reference cell. + * + * @param[out] values A vector of values of the given finite element field, + * at the quadrature points on the current object. + * + * @tparam InputVector The @p InputVector type must allow creation + * of an ArrayView object from it; this is satisfied by the + * `std::vector` class, among others. */ template void @@ -1799,7 +1883,10 @@ namespace FEValuesViews &divergences) const; /** - * @copydoc FEValuesViews::Tensor<2,dim,spacedim>::get_function_values_from_local_dof_values() + * This function relates to get_function_divergences() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void @@ -1834,7 +1921,10 @@ namespace FEValuesViews &gradients) const; /** - * @copydoc FEValuesViews::Tensor<2,dim,spacedim>::get_function_values_from_local_dof_values() + * This function relates to get_function_gradients() in the same way + * as get_function_values_from_local_dof_values() relates to + * get_function_values(). See the documentation of + * get_function_values_from_local_dof_values() for more information. */ template void