updated docstrings

Author: Uwe Hernandez Acosta

src/LorentzVectorBase.jl

@@ -1,9 +1,11 @@
 module LorentzVectorBase
 
 export coordinate_system, coordinate_names
+export available_accessors
 
 include("getter.jl")
 include("interface.jl")
+include("utility.jl")
 include("coordinate_systems/XYZT.jl")
 include("coordinate_systems/PxPyPzE.jl")
 include("coordinate_systems/PtEtaPhiM.jl")

src/coordinate_systems/PtEtaPhiM.jl

@@ -1,16 +1,50 @@
 """
-
     PtEtaPhiM <: AbstractCoordinateSystem
 
-Cylindrical coordinate system for four-momenta. Using this requires the implementation of the following interface functions:
+Represents the cylindrical coordinate system for four-momenta, commonly used in high-energy physics.
+This system expresses four-momentum components in terms of transverse momentum (`pt`), pseudorapidity (`eta`),
+azimuthal angle (`phi`), and mass (`mass`).
+
+To use this coordinate system with a custom four-momentum type, you must implement the following interface methods:
 
 ```julia
-pt(::CustomFourMomentum)
-eta(::CustomFourMomentum)
-phi(::CustomFourMomentum)
-mass(::CustomFourMomentum)
+LorentzVectorBase.pt(::CustomFourMomentum)    # Returns the transverse momentum
+LorentzVectorBase.eta(::CustomFourMomentum)   # Returns the pseudorapidity
+LorentzVectorBase.phi(::CustomFourMomentum)   # Returns the azimuthal angle
+LorentzVectorBase.mass(::CustomFourMomentum)  # Returns the mass
+```
+
+### Example
+
+The following example demonstrates how to define a custom four-momentum type and implement the required interface:
+
+```jldoctest
+julia> struct CustomFourMomentum
+           pt
+           eta
+           phi
+           mass
+       end
+
+julia> LorentzVectorBase.coordinate_system(::CustomFourMomentum) = LorentzVectorBase.PtEtaPhiM()
+
+julia> LorentzVectorBase.pt(p::CustomFourMomentum) = p.pt
+
+julia> LorentzVectorBase.eta(p::CustomFourMomentum) = p.eta
+
+julia> LorentzVectorBase.phi(p::CustomFourMomentum) = p.phi
+
+julia> LorentzVectorBase.mass(p::CustomFourMomentum) = p.mass
+
+julia> p = CustomFourMomentum(10.0, 2.5, 1.57, 0.105)
+CustomFourMomentum(10.0, 2.5, 1.57, 0.105)
+
+julia> isapprox(LorentzVectorBase.polar_angle(p), 2 * atan(exp(-2.5)))
+true
+
 ```
 
+By implementing these methods, the custom type `CustomFourMomentum` becomes compatible with `LorentzVectorBase` operations in the `PtEtaPhiM` coordinate system.
 """
 struct PtEtaPhiM <: AbstractCoordinateSystem end
 coordinate_names(::PtEtaPhiM) = (:pt, :eta, :phi, :mass)

src/coordinate_systems/PxPyPzE.jl

@@ -1,17 +1,50 @@
 
 """
-
     PxPyPzE <: AbstractCoordinateSystem
 
-Cartesian coordinate system for four-momenta. Using this requires the implementation of the following interface functions:
+Represents the Cartesian coordinate system for four-momenta, where the components are labeled as (px, py, pz, E).
+This system is commonly used in high-energy physics to describe the momentum and energy of particles.
+
+To use this coordinate system with a custom four-momentum type, you must implement the following interface methods:
 
 ```julia
-LorentzVectorBase.px(::CustomFourMomentum)
-LorentzVectorBase.py(::CustomFourMomentum)
-LorentzVectorBase.pz(::CustomFourMomentum)
-LorentzVectorBase.E(::CustomFourMomentum)
+LorentzVectorBase.px(::CustomFourMomentum)  # Returns the x-component of momentum
+LorentzVectorBase.py(::CustomFourMomentum)  # Returns the y-component of momentum
+LorentzVectorBase.pz(::CustomFourMomentum)  # Returns the z-component of momentum
+LorentzVectorBase.E(::CustomFourMomentum)   # Returns the energy component
+```
+
+### Example
+
+The following example demonstrates how to define a custom four-momentum type and implement the required interface:
+
+```jldoctest
+julia> struct CustomFourMomentum
+           px
+           py
+           pz
+           E
+       end
+
+julia> LorentzVectorBase.coordinate_system(::CustomFourMomentum) = LorentzVectorBase.PxPyPzE()
+
+julia> LorentzVectorBase.px(p::CustomFourMomentum) = p.px
+
+julia> LorentzVectorBase.py(p::CustomFourMomentum) = p.py
+
+julia> LorentzVectorBase.pz(p::CustomFourMomentum) = p.pz
+
+julia> LorentzVectorBase.E(p::CustomFourMomentum) = p.E
+
+julia> p = CustomFourMomentum(1.0, 2.0, 3.0, 4.0)
+CustomFourMomentum(1.0, 2.0, 3.0, 4.0)
+
+julia> isapprox(LorentzVectorBase.spatial_magnitude(p), sqrt(1.0^2 + 2.0^2 + 3.0^2))
+true
+
 ```
 
+By implementing these methods, the custom type `CustomFourMomentum` becomes compatible with `LorentzVectorBase` operations in the `PxPyPzE` coordinate system.
 """
 struct PxPyPzE <: AbstractCoordinateSystem end
 coordinate_names(::PxPyPzE) = (:px, :py, :pz, :E)

src/coordinate_systems/XYZT.jl

@@ -1,16 +1,47 @@
 """
-
     XYZT <: AbstractCoordinateSystem
 
-Cartesian coordinate system for four-vectors. Using this requires the implementation of the following interface functions:
+Represents the Cartesian coordinate system for four-vectors, where the components are labeled as (x, y, z, t).
+
+To use this coordinate system with a custom four-vector type, you must implement the following interface methods:
 
 ```julia
-LorentzVectorBase.x(::CustomFourVector)
-LorentzVectorBase.y(::CustomFourVector)
-LorentzVectorBase.z(::CustomFourVector)
-LorentzVectorBase.t(::CustomFourVector)
+LorentzVectorBase.x(::CustomFourVector)  # Returns the x-component
+LorentzVectorBase.y(::CustomFourVector)  # Returns the y-component
+LorentzVectorBase.z(::CustomFourVector)  # Returns the z-component
+LorentzVectorBase.t(::CustomFourVector)  # Returns the time component
+```
+
+### Example
+
+The following example demonstrates how to define a custom four-vector type and implement the required interface:
+
+```jldoctest
+julia> struct CustomLVector
+           x
+           y
+           z
+           t
+       end
+
+julia> LorentzVectorBase.coordinate_system(::CustomLVector) = LorentzVectorBase.XYZT()
+
+julia> LorentzVectorBase.x(lv::CustomLVector) = lv.x
+
+julia> LorentzVectorBase.y(lv::CustomLVector) = lv.y
+
+julia> LorentzVectorBase.z(lv::CustomLVector) = lv.z
+
+julia> LorentzVectorBase.t(lv::CustomLVector) = lv.t
+
+julia> c = CustomLVector(1, 2, 3, 4)
+CustomLVector(1, 2, 3, 4)
+
+julia> @assert isapprox(LorentzVectorBase.spatial_magnitude(c), sqrt(1^2 + 2^2 + 3^2))
+
 ```
 
+By implementing these methods, the custom type `CustomLVector` becomes compatible with `LorentzVectorBase` operations in the `XYZT` coordinate system.
 """
 struct XYZT <: AbstractCoordinateSystem end
 coordinate_names(::XYZT) = (:x, :y, :z, :t)