Make sure all exported functions have docstrings

Author: TacHawkes

src/AbstractTypes/AbstractRay.jl

@@ -79,7 +79,13 @@ abstract type AbstractRay{T <: Real} end
 Base.position(ray::AbstractRay) = ray.pos
 position!(ray::AbstractRay, pos) = (ray.pos = pos)
 
+"""
+    direction(ray::AbstractRay)
+
+Returns the direction vector of the `ray`.
+"""
 direction(ray::AbstractRay) = ray.dir
+
 function direction!(ray::AbstractRay, dir)
     ray.dir = normalize(dir)
     return nothing

src/Beam.jl

@@ -16,8 +16,14 @@ mutable struct Beam{T, R <: AbstractRay{T}} <: AbstractBeam{T, R}
     children::Vector{Beam{T, R}}
 end
 
+"""
+    rays(beam::Beam)
+
+Returns the vector of rays that make up the `beam`.
+"""
 rays(b::Beam) = b.rays
 
+
 Base.push!(b::Beam, ray::AbstractRay) = push!(b.rays, ray)
 
 function Beam(ray::R) where {T, R <: AbstractRay{T}}

src/Config.jl

@@ -9,42 +9,114 @@ using Preferences
 
 # --- Paraxial Invariants ---
 const INVARIANT_THRESHOLD = @load_preference("invariant_threshold", 1e-6)
+"""
+    get_invariant_threshold()
+
+Returns the global configuration threshold for the paraxial optical invariant check.
+"""
 get_invariant_threshold() = INVARIANT_THRESHOLD
 
+
 # --- SDF & Ray Marching ---
 const SDF_SURFACE_THRESHOLD = @load_preference("sdf_surface_threshold", 1e-9)
 const SDF_RAYMARCH_EPS = @load_preference("sdf_raymarch_eps", 1e-10)
 const SDF_INSIDE_STEP = @load_preference("sdf_inside_step", 1.0)
 
+"""
+    get_sdf_surface_threshold()
+
+Returns the global configuration threshold for the Signed Distance Field (SDF) surface detection.
+"""
 get_sdf_surface_threshold() = SDF_SURFACE_THRESHOLD
+
+"""
+    get_sdf_raymarch_eps()
+
+Returns the global configuration epsilon for the SDF ray marching algorithm.
+"""
 get_sdf_raymarch_eps() = SDF_RAYMARCH_EPS
+
+"""
+    get_sdf_inside_step()
+
+Returns the global configuration step size when inside an SDF volume.
+"""
 get_sdf_inside_step() = SDF_INSIDE_STEP
 
+
 # --- Numerical Thresholds ---
 const INTERNAL_REFLECTION_THRESHOLD = @load_preference("internal_reflection_threshold", 1e-6)
 const LINE_PLANE_INTERSECTION_THRESHOLD = @load_preference("line_plane_intersection_threshold", 1e-6)
 const ORTHOGONALITY_THRESHOLD = @load_preference("orthogonality_threshold", 1e-10)
 
+"""
+    get_internal_reflection_threshold()
+
+Returns the global configuration threshold for total internal reflection detection.
+"""
 get_internal_reflection_threshold() = INTERNAL_REFLECTION_THRESHOLD
+
+"""
+    get_line_plane_intersection_threshold()
+
+Returns the global configuration threshold for line-plane intersection calculations.
+"""
 get_line_plane_intersection_threshold() = LINE_PLANE_INTERSECTION_THRESHOLD
+
+"""
+    get_orthogonality_threshold()
+
+Returns the global configuration threshold for orthogonality checks (e.g., beam support axes).
+"""
 get_orthogonality_threshold() = ORTHOGONALITY_THRESHOLD
 
+
 # --- Tracing Defaults ---
 const DEFAULT_R_MAX = @load_preference("default_r_max", 100)
 const DEFAULT_DEPTH_MAX = @load_preference("default_depth_max", typemax(Int))
 
+"""
+    get_default_r_max()
+
+Returns the default maximum number of segments for ray tracing.
+"""
 get_default_r_max() = DEFAULT_R_MAX
+
+"""
+    get_default_depth_max()
+
+Returns the default maximum depth for recursive ray tracing (e.g., reflections/refractions).
+"""
 get_default_depth_max() = DEFAULT_DEPTH_MAX
 
+
 # --- Physical Defaults ---
 const DEFAULT_WAVELENGTH = @load_preference("default_wavelength", 1e-6)
 const DEFAULT_WAIST = @load_preference("default_waist", 1e-3)
 const DEFAULT_POWER = @load_preference("default_power", 1e-3)
 
+"""
+    get_default_wavelength()
+
+Returns the default wavelength in meters.
+"""
 get_default_wavelength() = DEFAULT_WAVELENGTH
+
+"""
+    get_default_waist()
+
+Returns the default beam waist radius in meters.
+"""
 get_default_waist() = DEFAULT_WAIST
+
+"""
+    get_default_power()
+
+Returns the default beam total power in Watts.
+"""
 get_default_power() = DEFAULT_POWER
 
+
 """
     set_preference!(key::String, val; persistent=true)
 
@@ -56,6 +128,13 @@ function set_preference!(key::String, val)
 end
 
 # Keep the old setter for compatibility
+"""
+    set_invariant_threshold!(val::Real)
+
+Sets the global configuration threshold for the paraxial optical invariant check.
+This preference is persistent. Please restart Julia for this to take effect.
+"""
 set_invariant_threshold!(val::Real) = set_preference!("invariant_threshold", Float64(val))
 
+
 end # module

src/OpticalComponents/NonInteractable.jl

@@ -19,4 +19,10 @@ set_new_origin3d!(d::NonInteractableObject) = set_new_origin3d!(d.shape)
 intersect3d(::NonInteractableObject, ::AbstractRay) = nothing
 interact3d(::AbstractSystem, ::NonInteractableObject, ::AbstractBeam, ::AbstractRay) = nothing
 
+"""
+    MeshDummy(loadpath::String)
+
+Creates a [`NonInteractableObject`](@ref) with a [`Mesh`](@ref) loaded from the specified file path.
+Useful for rendering background objects or geometry that does not interact with rays.
+"""
 MeshDummy(loadpath::String) = NonInteractableObject(Mesh(load(loadpath)))