Aos_2: doc fixes #7713
Merged
Aos_2: doc fixes #7713
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
|
||
| /*! Convert an integer to an algebraic number. | ||
| * \param z An integer. | ||
| * \return The algebraic number equivalent to z. |
There was a problem hiding this comment.
in the return maybe the z between backticks?
(analogous above and below for the q.
| /*! Obtain a range of double-precision floats that contains the given | ||
| * algebraic number. | ||
| * \param x The given number. | ||
| * \return A pair <x_lo, x_hi> that contain x. |
Comment on lines
72
to
74
| /*! Convert a sequence of rational coefficients to an equivalent sequence | ||
| * of integer coefficients. If the input coefficients are q(1), ..., q(k), | ||
| * where q(i) = n(i)/d(i) then the output coefficients will be of the |
There was a problem hiding this comment.
"formulas" in backticks?
Comment on lines
76
to
78
| * n(i) * lcm {d(1), ... , d(k)} | ||
| * a(i) = ------------------------------- | ||
| * d(i) * gcd {n(1), ... , n(k)} |
There was a problem hiding this comment.
total between triple backtics?
Comment on lines
84
to
85
| * \pre The value type of q_begin and q_end is `Rational`, and | ||
| * the value type of zoi is `Integer`. |
There was a problem hiding this comment.
Backticks here should be single quotes?
zoi, q_begin and q_end between backtics?
| * \param oi An output iterator for the real-valued solutions of the | ||
| * quadratic equation. | ||
| * \return A past-the-end iterator for the output container. | ||
| * \pre The value type of oi is Algebraic. |
Comment on lines
94
to
95
| * \return The square root of x. | ||
| * \pre x is non-negative. |
Comment on lines
+127
to
+128
| * \return Whether this polynomial is non-zero (false if the polynomial is | ||
| * zero). |
There was a problem hiding this comment.
false and zero in backticks?
| unsigned int degree, | ||
| Polynomial& poly, Integer& poly_denom) const; | ||
|
|
||
| /*! Construct two polynomials with integer coefficients such that P(x)/Q(x) |
There was a problem hiding this comment.
Stopped reviewing for backticks ...
| the `Topology_traits` type is selected based on the provided geometry | ||
| traits `Geometry_traits_2`, or more precisely, on the boundary | ||
| conditions defined by the geometry traits. If all sides of the | ||
| boundary of the parameter space are cosed, the instance |
|
All good points.
I believe that I addressed them all.
I also seized the opportunity and applied several other fixes mainly
related to output iterators.
NOTE: I wasn't able to fix the following perhaps due to a bug in doxygen.
It produces the following erroneous text (look for whereTypeis):
PreconditionDereferencing oi must yield an object of type std::pair<
Arrangement_on_surface_2::Vertex_const_handle,
std::pair<std::optional<Type,std::optional<Type>>>, whereTypeis
std::variant<Arrangement_on_surface_2::Vertex_const_handle,
Arrangement_on_surface_2::Halfedge_const_handle,
Arrangement_on_surface_2::Face_const_handle>`.
in the manual of decompose().
The source is
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h
____ _ ____ _
/_____/_) o /__________ __ //
(____ ( ( ( (_/ (_/-(-'_(/
_/
…On Thu, 14 Sept 2023 at 19:09, albert-github ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> +
+ /*! Obtain the numerator of a rational number.
+ * \param q A rational number.
+ * \return The numerator of q.
+ */
+ Integer numerator(const Rational& q) const;
+
+ /*! Obtain the denominator of a rational number.
+ * \param q A rational number.
+ * \return The denominator of q.
+ */
+ Integer denominator(const Rational& q) const;
+
+ /*! Convert an integer to an algebraic number.
+ * \param z An integer.
+ * \return The algebraic number equivalent to z.
in the return maybe the z between backticks?
(analogous above and below for the q.
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> + */
+ Algebraic convert(const Rational& q) const;
+
+ /*! Construct a rational number that lies strictly between two algebraic
+ * values.
+ * \param x1 The first algebraic value.
+ * \param x2 The second algebraic value.
+ * \pre The two values are not equal.
+ * \return A rational number that lies in the open interval (x1, x2).
+ */
+ Rational rational_in_interval(const Algebraic& x1, const Algebraic& x2) const;
+
+ /*! Obtain a range of double-precision floats that contains the given
+ * algebraic number.
+ * \param x The given number.
+ * \return A pair <x_lo, x_hi> that contain x.
Some backticks?
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> + /*! Convert a sequence of rational coefficients to an equivalent sequence
+ * of integer coefficients. If the input coefficients are q(1), ..., q(k),
+ * where q(i) = n(i)/d(i) then the output coefficients will be of the
"formulas" in backticks?
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> + * n(i) * lcm {d(1), ... , d(k)}
+ * a(i) = -------------------------------
+ * d(i) * gcd {n(1), ... , n(k)}
total between triple backtics?
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> + * \pre The value type of q_begin and q_end is `Rational`, and
+ * the value type of zoi is `Integer`.
Backticks here should be single quotes?
zoi, q_begin and q_end between backtics?
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> + /*! Compute the square root of an algebraic number.
+ * \param x The number.
+ * \return The square root of x.
+ * \pre x is non-negative.
+ */
+ Algebraic sqrt(const Algebraic& x) const;
+
+ /*! Compute the roots of a quadratic equations \f$a*x^2+ b*x + c = 0\f$
+ * with integer coefficients.
+ * \param a The coefficient of \f$x^2\f$
+ * \param b The coefficient of \f$x\f$
+ * \param c The free term.
+ * \param oi An output iterator for the real-valued solutions of the
+ * quadratic equation.
+ * \return A past-the-end iterator for the output container.
+ * \pre The value type of oi is Algebraic.
oi in backticks?
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> + * \return The square root of x.
+ * \pre x is non-negative.
x in backticks?
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> + * \return Whether this polynomial is non-zero (false if the polynomial is
+ * zero).
false and zero in backticks?
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h
<#7713 (comment)>:
> + unsigned int degree) const;
+
+ /*! Construct a polynomial with integer coefficients given rational
+ * coefficients.
+ * \param coeffs The coefficients of the input polynomial.
+ * \param degree The degree of the input polynomial.
+ * \param poly Output: The resulting polynomial with integer coefficients.
+ * \param poly_denom Output: The denominator for the polynomial.
+ * \return Whether this polynomial is non-zero (false if the polynomial is
+ * zero).
+ */
+ bool construct_polynomial(const Rational *coeffs,
+ unsigned int degree,
+ Polynomial& poly, Integer& poly_denom) const;
+
+ /*! Construct two polynomials with integer coefficients such that P(x)/Q(x)
Stopped reviewing for backticks ...
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt
<#7713 (comment)>:
> -contains one topology traits, namely,
-`Arr_spherical_topology_traits_2`. It can serve as a topology traits
-for an arrangement embedded on a sphere. More precisely, for an
+expose the concepts that refine the basic concept. The package
+contains three topology traits class templates, namely,
+`Arr_bounded_planar_topology_traits_2`,
+`Arr_unb_planar_topology_traits_2`, and
+`Arr_spherical_topology_traits_2`. The first two are internally used
+to define any instance of the class template
+`Arrangement_2<GeometryTraits_2, Dcel>`. In particular, an instance
+`Arrangement_2<Geometry_traits_2, Dcel_>` is derived from the instance
+`Arrangement_on_surface_2<Geometry_traits_2,Topology_traits>`, where
+the `Topology_traits` type is selected based on the provided geometry
+traits `Geometry_traits_2`, or more precisely, on the boundary
+conditions defined by the geometry traits. If all sides of the
+boundary of the parameter space are cosed, the instance
cosed -> closed
—
Reply to this email directly, view it on GitHub
<#7713 (review)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABVBNOCG7WN355LTH65WG63X2MTZXANCNFSM6AAAAAA4YFE2M4>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
|
|
1. doxygen --version
1.10.0 (7962329e20472152221c3e75ddafd81b9e8fca99)
2. It removes the spaces and results with: whereTypeis
while it should be: where Type is
____ _ ____ _
/_____/_) o /__________ __ //
(____ ( ( ( (_/ (_/-(-'_(/
_/
…On Tue, 19 Sept 2023 at 12:38, albert-github ***@***.***> wrote:
- which version of doxygen did you test with?
- what is exactly the problem (it is of course hard to describe over
email),
—
Reply to this email directly, view it on GitHub
<#7713 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABVBNOAR7SX6U3P4ITMO7D3X3FRZZANCNFSM6AAAAAA4YFE2M4>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
|
Do I see it correctly in Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h around line 43: the |
|
Indeed. Fixed. Thanks!!!
____ _ ____ _
/_____/_) o /__________ __ //
(____ ( ( ( (_/ (_/-(-'_(/
_/
…On Tue, 19 Sept 2023 at 13:23, albert-github ***@***.***> wrote:
Do I see it correctly in
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h
<https://github.com/CGAL/cgal/pull/7713/files#diff-aa8ff8c1b909e7f9f7e238637db2ba8f3ae181cf7b11b8fae56a4abccdf34491>
around line 43:
* \pre Dereferencing `oi` must yield an object of type
* `std::pair<Arrangement_on_surface_2::Vertex_const_handle,
* std::pair<std::optional<Type,std::optional<Type>>>,
* where `Type` is
the <Type>>>, shouldn't this be <Type>>>`,?
(so it looks to me that a backtick is missing)
—
Reply to this email directly, view it on GitHub
<#7713 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABVBNOB37NYNGKB5BZQ7UIDX3FXCBANCNFSM6AAAAAA4YFE2M4>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Comment on lines
1323
to
1326
| * \pre Dereferencing `oi` must yield a polymorphic object of type | ||
| * `std::variant<Arrangement_on_surface_2::Vertex_handle, | ||
| * Arrangement_on_surface_2::Halfedge_handle, | ||
| * Arrangement_on_surface_2::Face_handle>`. |
There was a problem hiding this comment.
In the nightly documentation test CGAL-6.0-Ic-67 (https://cgal.geometryfactory.com/CGAL/Manual_doxygen_test/CGAL-6.0-Ic-67/index.html) we get for the 1.9.6 version of doxygen the warnings:
/home/cgal-testsuite/cgal_doc_build/CGAL-6.0-Ic-67/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h:45: warning: explicit link request to 'variant' could not be resolved
/home/cgal-testsuite/cgal_doc_build/CGAL-6.0-Ic-67/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h:1324: warning: explicit link request to 'variant' could not be resolved
(as of doxygen version 1.9.7 this problem has been solved).
As a workaround the problem can be solved to reformulate the:
* `std::variant<Arrangement_on_surface_2::Vertex_handle,
* Arrangement_on_surface_2::Halfedge_handle,
* Arrangement_on_surface_2::Face_handle>`.
to
* `std::variant<Arrangement_on_surface_2::Vertex_handle, Arrangement_on_surface_2::Halfedge_handle, Arrangement_on_surface_2::Face_handle>`.
analogous for doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h
…ngle line to pacify older version of Doxygen
|
fixed
____ _ ____ _
/_____/_) o /__________ __ //
(____ ( ( ( (_/ (_/-(-'_(/
_/
…On Wed, 20 Sept 2023 at 12:12, albert-github ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In
Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h
<#7713 (comment)>:
> + * \pre Dereferencing `oi` must yield a polymorphic object of type
+ * `std::variant<Arrangement_on_surface_2::Vertex_handle,
+ * Arrangement_on_surface_2::Halfedge_handle,
+ * Arrangement_on_surface_2::Face_handle>`.
In the nightly documentation test CGAL-6.0-Ic-67 (
https://cgal.geometryfactory.com/CGAL/Manual_doxygen_test/CGAL-6.0-Ic-67/index.html)
we get for the 1.9.6 version of doxygen the warnings:
/home/cgal-testsuite/cgal_doc_build/CGAL-6.0-Ic-67/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h:45: warning: explicit link request to 'variant' could not be resolved
/home/cgal-testsuite/cgal_doc_build/CGAL-6.0-Ic-67/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h:1324: warning: explicit link request to 'variant' could not be resolved
(as of doxygen version 1.9.7 this problem has been solved).
As a workaround the problem can be solved to reformulate the:
* `std::variant<Arrangement_on_surface_2::Vertex_handle,
* Arrangement_on_surface_2::Halfedge_handle,
* Arrangement_on_surface_2::Face_handle>`.
to
* `std::variant<Arrangement_on_surface_2::Vertex_handle, Arrangement_on_surface_2::Halfedge_handle, Arrangement_on_surface_2::Face_handle>`.
analogous for
doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h
—
Reply to this email directly, view it on GitHub
<#7713 (review)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABVBNOCUVGHVGX5JDTJGRJTX3KXOFANCNFSM6AAAAAA4YFE2M4>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
|
Successfully tested in CGAL-6.0-Ic-84 |
lrineau
added
the
rm only: ready for master
lrineau
removed
the
rm only: ready for master
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary of Changes
Fixes documentation issues in the Aos_2 package
Release Management