docs: Improve documentation on surface classes (#2323)

In particular `LineSurface` after #2287.

Core/include/Acts/Definitions/Direction.hpp

@@ -84,8 +84,6 @@ class Direction final {
 
   /// Reverse the direction
   ///
-  /// @param dir is the direction at input
-  ///
   /// @return an opposite direction
   inline constexpr Direction invert() const {
     return (m_value == Value::Positive) ? Value::Negative : Value::Positive;

Core/include/Acts/Geometry/GeometryIdentifier.hpp

@@ -87,12 +87,18 @@ class GeometryIdentifier {
 
  private:
   // clang-format off
-  static constexpr Value kVolumeMask    = 0xff00000000000000; // (2^8)-1 = 255 volumes
-  static constexpr Value kBoundaryMask  = 0x00ff000000000000; // (2^8)-1 = 255 boundaries
-  static constexpr Value kLayerMask     = 0x0000fff000000000; // (2^12)-1 = 4095 layers
-  static constexpr Value kApproachMask  = 0x0000000ff0000000; // (2^8)-1 = 255 approach surfaces
-  static constexpr Value kSensitiveMask = 0x000000000fffff00; // (2^20)-1 = 1048575 sensitive surfaces
-  static constexpr Value kExtraMask     = 0x00000000000000ff; // (2^8)-1 = 255 extra values
+  /// (2^8)-1 = 255 volumes
+  static constexpr Value kVolumeMask    = 0xff00000000000000;
+  /// (2^8)-1 = 255 boundaries
+  static constexpr Value kBoundaryMask  = 0x00ff000000000000;
+  /// (2^12)-1 = 4095 layers
+  static constexpr Value kLayerMask     = 0x0000fff000000000;
+  /// (2^8)-1 = 255 approach surfaces
+  static constexpr Value kApproachMask  = 0x0000000ff0000000;
+  /// (2^20)-1 = 1048575 sensitive surfaces
+  static constexpr Value kSensitiveMask = 0x000000000fffff00;
+  /// (2^8)-1 = 255 extra values
+  static constexpr Value kExtraMask     = 0x00000000000000ff;
   // clang-format on
 
   Value m_value = 0;

Core/include/Acts/Surfaces/DiscSurface.hpp

@@ -33,15 +33,14 @@ class SurfaceBounds;
 
 /// @class DiscSurface
 ///
-/// Class for a DiscSurface in the, it inherits from Surface.
+/// Class for a disc surface (or a segment thereof)
 ///
-/// The DiscSurface has a polar local coordinate system, with
-/// (r,phi) describing the coordinates.
+/// The DiscSurface is defined by the local polar coordinates @f$ (r,phi) @f$.
 ///
-/// The surface transform positions the disc such, that the origin
-/// is at r=0, independent of the provided DiscBounds. The z-axis
-/// The normal vector of the Disc, being perpendicular to the
-/// radial direction.
+/// The surface transform positions the disc such that the origin
+/// is at @f$ r=0 @f$, independent of the provided \c DiscBounds.
+/// The normal vector of the disc (i.e., the local @f$z@f$-axis) is given by
+/// @f$ \vec e_{z} = \vec e_{r} \times\vec e_{phi} @f$.
 ///
 /// The disc surface The only surface type for which the
 /// covariance matrix is NOT given in the reference frame.
@@ -256,7 +255,7 @@ class DiscSurface : public Surface {
   /// @param bcheck The boundary check prescription
   /// @param tolerance the tolerance used for the intersection
   ///
-  ///  <b>mathematical motivation:</b>
+  /// <b>Mathematical motivation:</b>
   ///
   /// the equation of the plane is given by: <br>
   /// @f$ \vec n \cdot \vec x = \vec n \cdot \vec p,@f$ <br>

Core/include/Acts/Surfaces/LineSurface.hpp

@@ -161,32 +161,26 @@ class LineSurface : public Surface {
   Vector3 localToGlobal(const GeometryContext& gctx, const Vector2& lposition,
                         const Vector3& direction) const final;
 
-  /// Specified for LineSurface: global to local method without dynamic
-  /// memory allocation
+  /// Specified for `LineSurface`: global to local method without dynamic
+  /// memory allocation.
   ///
-  /// This method is the true global->local transformation.<br>
-  /// makes use of globalToLocal and indicates the sign of the Acts::eBoundLoc0
-  /// by the given momentum direction
+  /// This method is the true global -> local transformation. It makes use of
+  /// @c globalToLocal and indicates the sign of the @c Acts::eBoundLoc0
+  /// by the given momentum direction.
   ///
-  /// The calculation of the sign of the radius (or \f$ d_0 \f$) can be done as
-  /// follows:<br>
-  /// May \f$ \vec d = \vec m - \vec c \f$ denote the difference between the
+  /// The calculation of the sign of the radius (or @f$ d_0 @f$) can be done as
+  /// follows:
+  /// May @f$ \vec d = \vec m - \vec c @f$ denote the difference between the
   /// center of the line and the global position of the measurement/predicted
-  /// state,
-  /// then \f$ \vec d
-  /// \f$
-  /// lies within the so
-  /// called measurement plane.
-  /// The measurement plane is determined by the two orthogonal vectors \f$
-  /// \vec{measY}= \vec{Acts::eBoundLoc1} \f$
-  /// and \f$ \vec{measX} = \vec{measY} \times \frac{\vec{p}}{|\vec{p}|}
-  /// \f$.<br>
-  ///
-  /// The sign of the radius (\f$ d_{0} \f$ ) is then defined by the projection
-  /// of
-  /// \f$ \vec{d} \f$
-  /// onto \f$ \vec{measX} \f$:<br>
-  /// \f$ sign = -sign(\vec{d} \cdot \vec{measX}) \f$
+  /// state. Then, @f$ \vec d @f$ lies in the so-called measurement plane.
+  /// The latter is determined by the two orthogonal vectors @f$
+  /// \vec{\texttt{measY}} = \vec{e}_z @f$ and @f$
+  /// \vec{\texttt{measX}} = \vec{\texttt{measY}} \times
+  /// \frac{\vec{p}}{|\vec{p}|} @f$.
+  ///
+  /// The sign of the radius (or @f$ d_{0} @f$ ) is then defined by the projection
+  /// of @f$ \vec{d} @f$ on @f$ \vec{measX} @f$:<br> @f$ sign = -sign(\vec{d}
+  /// \cdot \vec{measX}) @f$
   ///
   /// @image html figures/SignOfDriftCircleD0.gif
   ///
@@ -196,48 +190,65 @@ class LineSurface : public Surface {
   /// @param direction global 3D momentum direction (optionally ignored)
   /// @param tolerance (unused)
   ///
-  /// @return a Result<Vector2> which can be !ok() if the operation fails
+  /// @return A `Result<Vector2>`, which is set to `!ok()` if the @p position is not
+  /// the point of closest approach to the line surface.
   Result<Vector2> globalToLocal(
       const GeometryContext& gctx, const Vector3& position,
       const Vector3& direction,
       double tolerance = s_onSurfaceTolerance) const final;
 
-  /// @brief Straight line intersection schema
+  /// Calculate the straight-line intersection with the line surface.
+  ///
+  /// <b>Mathematical motivation:</b>
+  ///
+  /// Given two lines in parameteric form:<br>
+  ///
+  /// @f$ \vec l_{a}(u) = \vec m_a + u \cdot \vec e_{a} @f$
+  ///
+  /// @f$ \vec l_{b}(\mu) = \vec m_b + \mu \cdot \vec e_{b} @f$
+  ///
+  /// The vector between any two points on the two lines is given by:
+  ///
+  /// @f$ \vec s(u, \mu) = \vec l_{b} - l_{a} = \vec m_{ab} + \mu
+  /// \cdot
+  /// \vec e_{b} - u \cdot \vec e_{a} @f$,
+  ///
+  /// where @f$ \vec m_{ab} = \vec m_{b} - \vec m_{a} @f$.
+  ///
+  /// @f$ \vec s(u_0, \mu_0) @f$ denotes the vector between the two
+  /// closest points
+  ///
+  /// @f$ \vec l_{a,0} = l_{a}(u_0) @f$ and @f$ \vec l_{b,0} =
+  /// l_{b}(\mu_0) @f$
+  ///
+  /// and is perpendicular to both, @f$ \vec e_{a} @f$ and @f$ \vec e_{b} @f$.
+  ///
+  /// This results in a system of two linear equations:
+  ///
+  /// - (i) @f$ 0 = \vec s(u_0, \mu_0) \cdot \vec e_a = \vec m_{ab} \cdot
+  /// \vec e_a + \mu_0 \vec e_a \cdot \vec e_b - u_0 @f$ <br>
+  /// - (ii) @f$ 0 = \vec s(u_0, \mu_0) \cdot \vec e_b = \vec m_{ab} \cdot
+  /// \vec e_b + \mu_0  - u_0 \vec e_b \cdot \vec e_a @f$ <br>
+  ///
+  /// Solving (i) and (ii) for @f$ u @f$ and @f$ \mu_0 @f$ yields:
+  ///
+  /// - @f$ u_0 = \frac{(\vec m_{ab} \cdot \vec e_a)-(\vec m_{ab} \cdot \vec
+  /// e_b)(\vec e_a \cdot \vec e_b)}{1-(\vec e_a \cdot \vec e_b)^2} @f$ <br>
+  /// - @f$ \mu_0 = - \frac{(\vec m_{ab} \cdot \vec e_b)-(\vec m_{ab} \cdot \vec
+  /// e_a)(\vec e_a \cdot \vec e_b)}{1-(\vec e_a \cdot \vec e_b)^2} @f$ <br>
+  ///
+  /// The function checks if @f$ u_0 \simeq 0@f$ to check if the current @p
+  /// position is at the point of closest approach, i.e. the intersection
+  /// point, in which case it will return an @c onSurace intersection result.
+  /// Otherwise, the path length from @p position to the point of closest
+  /// approach (@f$ u_0 @f$) is returned in a @c reachable intersection.
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position The global position as a starting point
   /// @param direction The global direction at the starting point
   ///        @note expected to be normalized
   /// @param bcheck The boundary check directive for the estimate
   /// @param tolerance the tolerance used for the intersection
-  ///
-  ///   <b>mathematical motivation:</b>
-  ///   Given two lines in parameteric form:<br>
-  ///   - @f$ \vec l_{a}(\lambda) = \vec m_a + \lambda \cdot \vec e_{a} @f$ <br>
-  ///   - @f$ \vec l_{b}(\mu) = \vec m_b + \mu \cdot \vec e_{b} @f$ <br>
-  ///   the vector between any two points on the two lines is given by:
-  ///   - @f$ \vec s(\lambda, \mu) = \vec l_{b} - l_{a} = \vec m_{ab} + \mu
-  ///   \cdot
-  ///  \vec e_{b} - \lambda \cdot \vec e_{a} @f$, <br>
-  ///   when @f$ \vec m_{ab} = \vec m_{b} - \vec m_{a} @f$.<br>
-  ///   @f$ \vec s(u, \mu_0) @f$  denotes the vector between the two
-  ///  closest points <br>
-  ///   @f$ \vec l_{a,0} = l_{a}(u) @f$ and @f$ \vec l_{b,0} =
-  ///  l_{b}(\mu_0) @f$ <br>
-  ///   and is perpendicular to both, @f$ \vec e_{a} @f$ and @f$ \vec e_{b} @f$.
-  ///
-  ///   This results in a system of two linear equations:<br>
-  ///   - (i) @f$ 0 = \vec s(u, \mu_0) \cdot \vec e_a = \vec m_ab \cdot
-  ///  \vec e_a + \mu_0 \vec e_a \cdot \vec e_b - u @f$ <br>
-  ///   - (ii) @f$ 0 = \vec s(u, \mu_0) \cdot \vec e_b = \vec m_ab \cdot
-  ///  \vec e_b + \mu_0  - u \vec e_b \cdot \vec e_a @f$ <br>
-  ///
-  ///   Solving (i), (ii) for @f$ u @f$ and @f$ \mu_0 @f$ yields:
-  ///   - @f$ u = \frac{(\vec m_ab \cdot \vec e_a)-(\vec m_ab \cdot \vec
-  ///  e_b)(\vec e_a \cdot \vec e_b)}{1-(\vec e_a \cdot \vec e_b)^2} @f$ <br>
-  ///   - @f$ \mu_0 = - \frac{(\vec m_ab \cdot \vec e_b)-(\vec m_ab \cdot \vec
-  ///  e_a)(\vec e_a \cdot \vec e_b)}{1-(\vec e_a \cdot \vec e_b)^2} @f$ <br>
-  ///
   /// @return is the intersection object
   SurfaceIntersection intersect(
       const GeometryContext& gctx, const Vector3& position,
@@ -252,10 +263,10 @@ class LineSurface : public Surface {
   double pathCorrection(const GeometryContext& gctx, const Vector3& position,
                         const Vector3& direction) const override;
 
-  /// This method returns the bounds of the Surface by reference */
+  /// This method returns the bounds of the surface by reference
   const SurfaceBounds& bounds() const final;
 
-  /// Return properly formatted class name for screen output */
+  /// Return properly formatted class name for screen output
   std::string name() const override;
 
   /// Calculate the derivative of path length at the geometry constraint or

docs/conf.py

@@ -68,7 +68,7 @@
 
 html_theme_options = {
     "collapse_navigation": False,
-    "navigation_depth": 3,
+    "navigation_depth": 4,
     "prev_next_buttons_location": None,  # no prev/next links
     "style_external_links": True,
 }

docs/core/core.rst

@@ -5,7 +5,7 @@ The Acts core functionality is grouped into modules, where each module contains
 tools related to one particular subject, i.e. experiment geometry or vertexing.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    definitions/algebra
    definitions/units

docs/core/experimental_geometry.md

@@ -3,7 +3,8 @@
 # Experimental Geometry module
 
 :::{note}
-This module is in production and is under the namespace `Acts::Experimental`.
+This module is not considered production-ready yet, and is under the namespace
+`Acts::Experimental`.
 :::
 
 ## Overview