Add doxygen documentation of python functions

diff --git a/contrib/python-bindings/source/export_triangulation.cc b/contrib/python-bindings/source/export_triangulation.cc
index 332f2a5994ee6d6410e0885202c51970f55f34d0..18aeba4b474d68e78134efa2253d330600029f7b 100644 (file)
--- a/contrib/python-bindings/source/export_triangulation.cc
+++ b/contrib/python-bindings/source/export_triangulation.cc
@@ -776,7 +776,7 @@ namespace python
       .def("generate_truncated_cone",
            &TriangulationWrapper::generate_truncated_cone,
            generate_truncated_cone_overloads(
-             boost::python::args("self", "radius_0", "radius", "half_length"),
+             boost::python::args("self", "radius_0", "radius_2", "half_length"),
              generate_truncated_cone_docstring))
       .def("generate_hyper_shell",
            &TriangulationWrapper::generate_hyper_shell,

diff --git a/include/deal.II/grid/grid_generator.h b/include/deal.II/grid/grid_generator.h
index 3f0410cf2e198d5ee1bb19efdfefd5cacbec2bcc..1786bdc7756567ea49538905f0d7660868365d2a 100644 (file)
--- a/include/deal.II/grid/grid_generator.h
+++ b/include/deal.II/grid/grid_generator.h
@@ -94,6 +94,10 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_hyper_cube(left = 0., right = 1., colorize =
+   * false)`.
    */
   template <int dim, int spacedim>
   void
@@ -128,6 +132,9 @@ namespace GridGenerator
    *
    * @note Implemented for <tt>Triangulation@<2,2@></tt>,
    * <tt>Triangulation@<3,3@></tt>.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_simplex(vertices)`.
    */
   template <int dim>
   void
@@ -170,6 +177,9 @@ namespace GridGenerator
    * @param right Upper bound for the interval used to create the hyper cube.
    *
    * @param colorize Assign different boundary ids if set to true.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_subdivided_hyper_cube(left = 0., right = 1.)`.
    */
   template <int dim, int spacedim>
   void
@@ -213,6 +223,9 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_hyper_rectangle(p1, p2, colorize = false)`.
    */
   template <int dim, int spacedim>
   void
@@ -269,6 +282,10 @@ namespace GridGenerator
    *
    * @param colorize Assign different boundary ids if set to true. The same
    * comments apply as for the hyper_rectangle() function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_subdivided_hyper_rectangle(repetitions, p1, p2,
+   * colorize = false)`.
    */
   template <int dim, int spacedim>
   void
@@ -292,6 +309,10 @@ namespace GridGenerator
    *
    * The step sizes have to add up to the dimensions of the hyper rectangle
    * specified by the points @p p1 and @p p2.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_subdivided_steps_hyper_rectangle(step_sizes, p1,
+   * p2, colorize = false)`.
    */
   template <int dim>
   void
@@ -310,6 +331,10 @@ namespace GridGenerator
    * the domain will have a void there.
    *
    * @note If you need a lot of holes, you may consider cheese().
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_subdivided_material_hyper_rectangle(spacing, p,
+   * material_id, colorize = false)`.
    */
   template <int dim>
   void
@@ -342,6 +367,9 @@ namespace GridGenerator
    * calling this function.
    *
    * @param holes Positive number of holes in each of the dim directions.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_cheese(holes)`.
    */
   template <int dim, int spacedim>
   void
@@ -390,6 +418,12 @@ namespace GridGenerator
    *
    * @p tria is the triangulation to be created. It needs to be empty upon
    * calling this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_plate_with_a_holes(inner_radius = 0.4, outer_radius
+   * = 1, pad_bottom = 2, pad_top = 2., pad_left = 1., pad_right, center =
+   * Point(), polar_manifold = 0, tfi_manifold = 1, L = 1, n_slices = 2,
+   * colorize = false)`.
    */
   template <int dim>
   void
@@ -494,6 +528,10 @@ namespace GridGenerator
    * url       = {https://doi.org/10.1007/978-3-322-89849-4_39}
    * }
    * @endcode
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_channel_with_cylinder(shell_region_width = 0.03,
+   * n_shellsa = 2, skewness = 2., colorize = false)`.
    */
   template <int dim>
   void
@@ -522,6 +560,9 @@ namespace GridGenerator
    * @param tria The triangulation that will be created
    * @param vertices The 2^dim vertices of the cell
    * @param colorize If true, set different boundary ids.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_general_cell(vertices, colorize = false)`.
    */
   template <int dim, int spacedim>
   void
@@ -544,6 +585,9 @@ namespace GridGenerator
    *
    * @param colorize Assign different boundary ids if true. (see
    * @ref GlossColorization "the glossary entry on colorization").
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_parallelogram(vertices, colorize = false)`.
    */
   template <int dim>
   void
@@ -565,6 +609,9 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_parallelepiped(vertices, colorize = false)`.
    */
   template <int dim>
   void
@@ -582,6 +629,10 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_fixed_subdivided_parallelepiped(n_subdivisions,
+   * corners, colorize = false)`.
    */
   template <int dim>
   void
@@ -597,6 +648,10 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_varying_subdivided_parallelepiped(n_subdivisions,
+   * corners, colorize = false)`.
    */
   template <int dim>
   void
@@ -655,6 +710,10 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_hyper_cube(left = 0, right = 1., thickness = 1.,
+   * colorize = false)`.
    */
   template <int dim>
   void
@@ -739,6 +798,9 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_hyper_ball(point, radius = 1.)`.
    */
   template <int dim>
   void
@@ -778,6 +840,9 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_hyper_ball_balanced(point = Point(), radius = 1.)`.
    */
   template <int dim>
   void
@@ -860,6 +925,9 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_hyper_sphere(center, radius = 1.)`.
    */
   template <int spacedim>
   void
@@ -899,6 +967,9 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_quarter_hyper_ball(center, radius = 1.)`.
    */
   template <int dim>
   void
@@ -917,6 +988,9 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_half_hyper_ball(center, radius = 1.)`.
    */
   template <int dim>
   void
@@ -946,6 +1020,9 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_cylinder(radius = 1., half_length = 1.)`.
    */
   template <int dim>
   void
@@ -986,6 +1063,10 @@ namespace GridGenerator
    * @param radius The radius of the circle in the yz-plane used to extrude the cylinder.
    *
    * @param half_length The half-length of the cylinder in the x direction.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_subdivided_cylinder(x_subdivisions, radius = 1.,
+   * half_length = 1.)`.
    */
   template <int dim>
   void
@@ -1024,6 +1105,10 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_truncated_cone(radius_0 = 1., radius_2 = 0.5,
+   * half_length = 1.)`.
    */
   template <int dim>
   void
@@ -1357,6 +1442,10 @@ namespace GridGenerator
    *
    * @pre The triangulation passed as argument needs to be empty when calling
    * this function.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_hyper_shell(center, inner_radius, outer_radius,
+   * n_cells = 0, colorize = false)`.
    */
   template <int dim>
   void
@@ -1608,6 +1697,10 @@ namespace GridGenerator
    * flat faces (0 to 3 in 2d, 0 to 5 in 3d) plus the curved hole (4 in 2d,
    * and 6 in 3d). If @p colorize is set to false, then flat faces get the
    * number 0 and the hole gets number 1.
+   *
+   * @note This function is available through the python interface as
+   * `triangulation.generate_hyper_cube_with_cylindrical_hole(inner_radius =
+   * 0.25, outer_radius = 0.5, L = 0.5, repetitions = 1, colorize = false)`.
    */
   template <int dim>
   void
@@ -1930,6 +2023,10 @@ namespace GridGenerator
    *                                       false,
    *                                       false);
    * @endcode
+   *
+   * @note This function is available through the python interface as
+   * `result.merge_triangulations(triangulations, duplicated_vertex_tolerance =
+   * 1e-12, copy_manifold_ids = false)`.
    */
   template <int dim, int spacedim>
   void
@@ -1986,6 +2083,9 @@ namespace GridGenerator
    * are not aligned with the coordinate axes then the copies might not share
    * common faces; i.e., this function is intended for simple geometries with
    * boundary faces aligned along the coordinate axes.
+   *
+   * @note This function is available through the python interface as
+   * `result.replicate_triangulation(input, extents)`.
    */
   template <int dim, int spacedim = dim>
   void
@@ -2147,6 +2247,9 @@ namespace GridGenerator
    * @note Since @p input and @p output have different spatial dimensions, no
    * manifold objects are copied by this function regardless of the value of
    * @p copy_manifold_ids.
+   *
+   * @note This function is available through the python interface as
+   * `input.extrude_triangulation(n_slices, height, result)`.
    */
   void
   extrude_triangulation(
@@ -2250,6 +2353,9 @@ namespace GridGenerator
    * @note Since @p input and @p output have different spatial dimensions, no
    * manifold objects are copied by this function: you must attach new
    * manifold objects to @p out_tria.
+   *
+   * @note This function is available through the python interface as
+   * `in_tria.flatten_triangulation(out_tria)`.
    */
   template <int dim, int spacedim1, int spacedim2>
   void
@@ -2289,6 +2395,9 @@ namespace GridGenerator
    *
    * Also see
    * @ref simplex "Simplex support".
+   *
+   * @note This function is available through the python interface as
+   * `in_tria.convert_hypercube_to_simplex_mesh(out_tria)`.
    */
   template <int dim, int spacedim>
   void