(Potential) confusing documentation

[albert-github]

trafficstars

Issue Details

In quite a few files the sentence "Same as above" is present:

Boolean_set_operations_2/test/Boolean_set_operations_2/data/agg_op/README.txt CGAL_ipelets/doc/CGAL_ipelets/CGAL/CGAL_Ipelet_base.h Convex_hull_3/doc/Convex_hull_3/Concepts/ConvexHullTraits_3.h HalfedgeDS/examples/HalfedgeDS/hds_prog_compact.cpp HalfedgeDS/examples/HalfedgeDS/hds_prog_compact2.cpp Hyperbolic_triangulation_2/doc/Hyperbolic_triangulation_2/CGAL/Hyperbolic_Delaunay_triangulation_2.h Interpolation/doc/Interpolation/CGAL/natural_neighbor_coordinates_2.h Interpolation/doc/Interpolation/CGAL/regular_neighbor_coordinates_2.h Interpolation/doc/Interpolation/CGAL/surface_neighbors_3.h Interpolation/doc/Interpolation/CGAL/surface_neighbor_coordinates_3.h Interpolation/examples/Interpolation/README Interpolation/include/CGAL/natural_neighbor_coordinates_2.h Interpolation/include/CGAL/regular_neighbor_coordinates_2.h Interpolation/include/CGAL/sibson_gradient_fitting.h Kernel_23/doc/Kernel_23/CGAL/Kernel/global_functions.h Kernel_23/include/CGAL/Kernel/solve.h Mesh_3/doc/Mesh_3/Concepts/MeshComplexWithFeatures_3InTriangulation_3.h Mesh_3/doc/Mesh_3/Concepts/MeshComplex_3InTriangulation_3.h Periodic_2_triangulation_2/doc/Periodic_2_triangulation_2/CGAL/Periodic_2_Delaunay_triangulation_2.h Periodic_2_triangulation_2/doc/Periodic_2_triangulation_2/CGAL/Periodic_2_triangulation_2.h Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_triangulation_3.h Periodic_4_hyperbolic_triangulation_2/doc/Periodic_4_hyperbolic_triangulation_2/CGAL/Periodic_4_hyperbolic_triangulation_2.h Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/random_perturbation.h Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/self_intersections.h Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/triangulate_hole.h Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/Weights.h Polynomial/include/CGAL/Polynomial/square_free_factorize.h Principal_component_analysis_LGPL/include/CGAL/centroid.h Segment_Delaunay_graph_2/doc/Segment_Delaunay_graph_2/CGAL/Segment_Delaunay_graph_2.h Set_movable_separability_2/doc/Set_movable_separability_2/CGAL/Set_movable_separability_2/Single_mold_translational_casting/is_pullout_direction.h Set_movable_separability_2/doc/Set_movable_separability_2/CGAL/Set_movable_separability_2/Single_mold_translational_casting/pullout_directions.h Set_movable_separability_2/doc/Set_movable_separability_2/CGAL/Set_movable_separability_2/Single_mold_translational_casting/top_edges.h Set_movable_separability_2/include/CGAL/Set_movable_separability_2/Single_mold_translational_casting/is_pullout_direction.h Set_movable_separability_2/include/CGAL/Set_movable_separability_2/Single_mold_translational_casting/pullout_directions.h Set_movable_separability_2/include/CGAL/Set_movable_separability_2/Single_mold_translational_casting/top_edges.h STL_Extension/doc/STL_Extension/CGAL/Multiset.h Surface_mesh_parameterization/include/CGAL/Surface_mesh_parameterization/Orbifold_Tutte_parameterizer_3.h TDS_2/doc/TDS_2/Concepts/TriangulationDataStructure_2.h TDS_3/doc/TDS_3/Concepts/TriangulationDataStructure_3.h Triangulation/doc/Triangulation/CGAL/Delaunay_triangulation.h Triangulation/doc/Triangulation/CGAL/Regular_triangulation.h Triangulation/doc/Triangulation/CGAL/Triangulation.h Triangulation/doc/Triangulation/CGAL/Triangulation_vertex.h Triangulation/doc/Triangulation/Concepts/TriangulationDataStructure.h Triangulation/doc/Triangulation/Concepts/TriangulationVertex.h Triangulation_2/doc/Triangulation_2/CGAL/Constrained_Delaunay_triangulation_2.h Triangulation_2/doc/Triangulation_2/CGAL/Constrained_triangulation_plus_2.h Triangulation_2/doc/Triangulation_2/CGAL/Triangulation_2.h Triangulation_3/doc/Triangulation_3/CGAL/Delaunay_triangulation_3.h Triangulation_3/doc/Triangulation_3/CGAL/Regular_triangulation_3.h Triangulation_3/doc/Triangulation_3/CGAL/Triangulation_3.h Triangulation_3/test/Triangulation_3/include/CGAL/_test_cls_delaunay_3.h

This is potential confusing as the relative "same as above" might not be valid, especially when the sorting is different (SORT_MEMBER_DOCS / SORT_BRIEF_DOCS). I looked a bit closer to the locate function on the page doc_output/Periodic_2_triangulation_2/classCGAL_1_1Periodic__2__triangulation__2.html. I think that here there are the following possible solutions:

• use \copydoc (or \copybrief and / or \copydetails to the other function
• use \ref to the other function (plus some text)
• use \overload (I'm not happy with the overload text from doxygen either as this uses the word 'above' as well, resulting in the enhancement request (https://github.com/doxygen/doxygen/issues/6879). An alternative might be the use of something like: ALIASES = "overloaded{1}=This function is an overloaded function of \ref \1" ).

Note I saw also places (same file, function is_face) with just the text 'as above'

[ShatakshiSonker]

Hey, I am suffering lots of problem while setting up the environment. Can you point some resource to set-up from scratch. I cant find any clear source. Thanks in advance

[albert-github]

What to do?

Note milestone is set to 5.7-beta but I don't think this version will ever exist and should probably be set to 6.0 or better the issue should be solved.

[MaelRL]

This is only a visual bug from github, that milestone was renamed to 6.0 and it shows 6.0 if you click the link or check:

[albert-github]

Making a simple user go haywire ... (As indicated not a CGAL problem).