fix code style issues

* remove random whitespace
* remove redundant comments above docstrings
* fix docstrings to follow existing conventions
* fix many function type signatures
* move exports to top of files to provide clear submodule headers
* Int -> Integer
* added empty docstrings for generate, visual_size and apply
  these functions clearly need documentation

src/Optical/Emitters/AngularPower.jl

@@ -1,31 +1,26 @@
 module AngularPower
+export Lambertian, Cosine, Gaussian
 
-using ....OpticSim, ...Geometry
+using ....OpticSim
 using ...Emitters
+using ...Geometry
 using LinearAlgebra
 
 abstract type AbstractAngularPowerDistribution{T<:Real} end
 
-#---------------------------------------
-# Lambertian
-#---------------------------------------
 """
+    Lambertian{T} <: AbstractAngularPowerDistribution{T} 
+
 Ray power is unaffected by angle.
 """
-struct Lambertian{T} <: AbstractAngularPowerDistribution{T} 
+struct Lambertian{T} <: AbstractAngularPowerDistribution{T}
     Lambertian(::Type{T} = Float64) where {T<:Real} = new{T}()
 end
 
-function Emitters.apply(d::Lambertian{T}, Tr::Transform{T}, power::T, ray::OpticSim.Ray{T,3}) where {T}
-    return power
-end
-export Lambertian
+Emitters.apply(::Lambertian, ::Transform, ::Real, ::OpticSim.Ray{<:Real,3}) = power
 
-#---------------------------------------
-# Cosine Power Distribution
-#---------------------------------------
 """
-    Cosine(cosine_exp::T = one(T)) where {T<:Real}
+    Cosine{T} <: AbstractAngularPowerDistribution{T} 
 
 Cosine power distribution. Ray power is calculated by:
 
@@ -38,45 +33,33 @@ struct Cosine{T} <: AbstractAngularPowerDistribution{T}
         new{T}(cosine_exp)
     end
 end
-export Cosine
 
-# returning ray power
-function Emitters.apply(d::Cosine{T}, Tr::Transform{T}, power::T, ray::OpticSim.Ray{T,3}) where {T}
-    cosanglebetween = dot(OpticSim.direction(ray), forward(Tr))
-    power = power * cosanglebetween ^ d.cosine_exp
-    return power
+function Emitters.apply(d::Cosine, tr::Transform, power::Real, ray::OpticSim.Ray{<:Real,3})
+    cosanglebetween = dot(OpticSim.direction(ray), forward(tr))
+    return power * cosanglebetween ^ d.cosine_exp
 end
 
-#---------------------------------------
-# Gaussian Power Distribution
-#---------------------------------------
 """
-    Gaussian(gaussianu::T, gaussianv::T) where {T<:Real}
+    Gaussian{T} <: AbstractAngularPowerDistribution{T} 
 
 GGaussian power distribution. Ray power is calculated by:
 
 `power = power * exp(-(gaussianu * l^2 + gaussianv * m^2))`
 where l and m are the cos_angles between the two axes respectivly.
 """
-struct Gaussian{T} <: AbstractAngularPowerDistribution{T} 
+struct Gaussian{T} <: AbstractAngularPowerDistribution{T}
     gaussianu::T
     gaussianv::T
 
     function Gaussian(gaussianu::T, gaussianv::T) where {T<:Real}
         new{T}(gaussianu, gaussianv)
     end
 end
-export Gaussian
-
-# returning ray power
-function Emitters.apply(d::Gaussian{T}, Tr::Transform{T}, power::T, ray::OpticSim.Ray{T,3}) where {T}
 
-    l = dot(OpticSim.direction(ray), right(Tr))
-    m = dot(OpticSim.direction(ray), up(Tr))
-    power = power * exp(-(d.gaussianu * l^2 + d.gaussianv * m^2))
-
-    return power
+function Emitters.apply(d::Gaussian, tr::Transform, power::Real, ray::OpticSim.Ray{<:Real,3})
+    l = dot(OpticSim.direction(ray), right(tr))
+    m = dot(OpticSim.direction(ray), up(tr))
+    return power * exp(-(d.gaussianu * l^2 + d.gaussianv * m^2))
 end
 
-
 end # module Angular Power

src/Optical/Emitters/Directions.jl

@@ -1,26 +1,22 @@
 module Directions
+export Constant, RectGrid, UniformCone, HexapolarCone
 
-using ....OpticSim, ...Geometry
+using ....OpticSim
 using ...Emitters
+using ...Geometry
 using LinearAlgebra
 
 abstract type AbstractDirectionDistribution{T<:Real} end
 
-#---------------------------------------
-# Direction Distrubution Common Utilities
-#---------------------------------------
-
 Base.iterate(a::AbstractDirectionDistribution, state = 1) = state > length(a) ? nothing : (generate(a, state - 1), state + 1)
 Base.getindex(a::AbstractDirectionDistribution, index) = generate(a, index)
 Base.firstindex(a::AbstractDirectionDistribution) = 0
 Base.lastindex(a::AbstractDirectionDistribution) = length(a) - 1
 Base.copy(a::AbstractDirectionDistribution) = a # most don't have any heap allocated stuff so don't really need copying
 
-
-#---------------------------------------
-# Constant Ray Direction
-#---------------------------------------
 """
+    Constant{T} <: AbstractDirectionDistribution{T}
+
 Encapsulates a single ray direction, where the default direction is unitZ3 [0, 0, 1].
 
 ```julia
@@ -34,23 +30,19 @@ struct Constant{T} <: AbstractDirectionDistribution{T}
     function Constant(direction::Vec3{T}) where {T<:Real}
         return new{T}(direction)
     end
-    
+
     function Constant(::Type{T} = Float64) where {T<:Real}
         direction = unitZ3(T)
         return new{T}(direction)
     end
 end
-export Constant
 
-Base.length(d::Constant{T}) where {T} = 1
-function Emitters.generate(d::Constant{T}, n::Int) where {T<:Real}
-    return d.direction
-end
+Base.length(d::Constant) = 1
+Emitters.generate(d::Constant, ::Integer) = d.direction
 
-#---------------------------------------
-# Grid  Ray Distribution
-#---------------------------------------
 """
+    RectGrid{T} <: AbstractDirectionDistribution{T}
+
 Encapsulates a single ray direction, where the default direction is unitZ3 [0, 0, 1].
 
 ```julia
@@ -62,72 +54,68 @@ struct RectGrid{T} <: AbstractDirectionDistribution{T}
     direction::Vec3{T}
     halfangleu::T
     halfanglev::T
-    nraysu::Int
-    nraysv::Int
+    nraysu::Integer
+    nraysv::Integer
     uvec::Vec3{T}
     vvec::Vec3{T}
 
-    function RectGrid(direction::Vec3{T}, halfangleu::T, halfanglev::T, numraysu::Int, numraysv::Int) where {T<:Real}
+    function RectGrid(direction::Vec3{T}, halfangleu::T, halfanglev::T, numraysu::Integer, numraysv::Integer) where {T<:Real}
         (uvec, vvec) = get_uv_vectors(direction)
         return new{T}(direction, halfangleu, halfanglev, numraysu, numraysv, uvec, vvec)
     end
 
-    function RectGrid(halfangleu::T, halfanglev::T, numraysu::Int, numraysv::Int) where {T<:Real}
+    function RectGrid(halfangleu::T, halfanglev::T, numraysu::Integer, numraysv::Integer) where {T<:Real}
         direction, uvec, vvec = (unitZ3(T), unitX3(T), unitY3(T))
         return new{T}(direction, halfangleu, halfanglev, numraysu, numraysv, uvec, vvec)
     end
 end
-export RectGrid
 
-Base.length(d::RectGrid{T}) where {T} = d.nraysu * d.nraysv
-function Emitters.generate(d::RectGrid{T}, n::Int) where {T<:Real}
+Base.length(d::RectGrid) = d.nraysu * d.nraysv
+function Emitters.generate(d::RectGrid{T}, n::Integer) where {T<:Real}
     direction = d.direction
     uvec = d.uvec
     vvec = d.vvec
 
     # distributing evenly across the area of the rectangle which subtends the given angle (*not* evenly across the angle range)
     dindex = mod(n, d.nraysu * d.nraysv)
-    v = d.nraysv == 1 ? zero(T) : 2 * Int(floor(dindex / d.nraysu)) / (d.nraysv - 1) - 1.0
+    v = d.nraysv == 1 ? zero(T) : 2 * Integer(floor(dindex / d.nraysu)) / (d.nraysv - 1) - 1.0
     u = d.nraysu == 1 ? zero(T) : 2 * mod(dindex, d.nraysu) / (d.nraysu - 1) - 1.0
     θu = atan(u * tan(d.halfangleu) / 2) * d.halfangleu
     θv = atan(v * tan(d.halfanglev) / 2) * d.halfanglev
     dir = cos(θv) * (cos(θu) * direction + sin(θu) * uvec) + sin(θv) * vvec
     return dir
 end
 
-
-#---------------------------------------
-# Cone Ray Distribution
-#---------------------------------------
 """
+    UniformCone{T} <: AbstractDirectionDistribution{T}
+
 Encapsulates `numsamples` rays sampled uniformly from a cone with max angle θmax.
 
 ```julia
-UniformCone(direction::Vec3{T}, θmax::T, numsamples::Int) where {T<:Real}
-UniformCone(θmax::T, numsamples::Int) where {T<:Real}
+UniformCone(direction::Vec3{T}, θmax::T, numsamples::Integer) where {T<:Real}
+UniformCone(θmax::T, numsamples::Integer) where {T<:Real}
 ```
 """
 struct UniformCone{T} <: AbstractDirectionDistribution{T}
     direction::Vec3{T}
     θmax::T
-    numsamples::Int
+    numsamples::Integer
     uvec::Vec3{T}
     vvec::Vec3{T}
 
-    function UniformCone(direction::Vec3{T}, θmax::T, numsamples::Int) where {T<:Real}
+    function UniformCone(direction::Vec3{T}, θmax::T, numsamples::Integer) where {T<:Real}
         (uvec, vvec) = get_uv_vectors(direction)
         return new{T}(direction, θmax, numsamples, uvec, vvec)
     end
 
-    function UniformCone(θmax::T, numsamples::Int) where {T<:Real}
+    function UniformCone(θmax::T, numsamples::Integer) where {T<:Real}
         direction, uvec, vvec = (unitZ3(T), unitX3(T), unitY3(T))
         return new{T}(direction, θmax, numsamples, uvec, vvec)
     end
 end
-export UniformCone
 
-Base.length(d::UniformCone{T}) where {T} = d.numsamples
-function Emitters.generate(d::UniformCone{T}, n::Int) where {T<:Real}
+Base.length(d::UniformCone) = d.numsamples
+function Emitters.generate(d::UniformCone{T}, ::Integer) where {T<:Real}
     direction = d.direction
     θmax = d.θmax
     uvec = d.uvec
@@ -138,41 +126,38 @@ function Emitters.generate(d::UniformCone{T}, n::Int) where {T<:Real}
     return normalize(sin(θ) * (cos(ϕ) * uvec + sin(ϕ) * vvec) + cos(θ) * direction)
 end
 
-#----------------------------------------------------------------------------
-# Cone Ray Hexapolar Distribution
-#-----------------------------------------------------------------------------
 """
+    HexapolarCone{T} <: AbstractDirectionDistribution{T}
+
 Rays are generated by sampling a cone with θmax angle in an hexapolar fashion. The number of rays depends on the requested rings and is computed using the following formula:
-`1 + round(Int, (nrings * (nrings + 1) / 2) * 6)`
+`1 + round(Integer, (nrings * (nrings + 1) / 2) * 6)`
 
 ```julia
-HexapolarCone(direction::Vec3{T}, θmax::T, nrings::Int) where {T<:Real}
-HexapolarCone(θmax::T, nrings::Int = 3) where {T<:Real}
+HexapolarCone(direction::Vec3{T}, θmax::T, nrings::Integer) where {T<:Real}
+HexapolarCone(θmax::T, nrings::Integer = 3) where {T<:Real}
 ```
 """
 struct HexapolarCone{T} <: AbstractDirectionDistribution{T}
     direction::Vec3{T}
     θmax::T
-    nrings::Int
+    nrings::Integer
     uvec::Vec3{T}
     vvec::Vec3{T}
 
-    function HexapolarCone(direction::Vec3{T}, θmax::T, nrings::Int) where {T<:Real}
+    function HexapolarCone(direction::Vec3{T}, θmax::T, nrings::Integer) where {T<:Real}
         (uvec, vvec) = get_orthogonal_vectors(direction)
         return new{T}(direction, θmax, nrings, uvec, vvec)
     end
 
     # assume canonical directions
-    function HexapolarCone(θmax::T, nrings::Int = 3) where {T<:Real}
+    function HexapolarCone(θmax::T, nrings::Integer = 3) where {T<:Real}
         direction, uvec, vvec = (unitZ3(T), unitX3(T), unitY3(T))
         return new{T}(direction, θmax, nrings, uvec, vvec)
     end
 end
-export HexapolarCone
-
 
-Base.length(d::HexapolarCone{T}) where {T} = 1 + round(Int, (d.nrings * (d.nrings + 1) / 2) * 6)
-function Emitters.generate(d::HexapolarCone{T}, n::Int) where {T<:Real}
+Base.length(d::HexapolarCone) = 1 + round(Integer, (d.nrings * (d.nrings + 1) / 2) * 6)
+function Emitters.generate(d::HexapolarCone{T}, n::Integer) where {T<:Real}
     dir = d.direction
     θmax = d.θmax
     uvec = d.uvec

src/Optical/Emitters/Emitters.jl

@@ -4,34 +4,48 @@ These are intrinsic physical properties of the emitter.
 =#
 
 module Emitters
+export generate, visual_size, apply
+export right, up, forward
+export Spectrum, Directions, Origins, AngularPower, Sources
 
 using ...OpticSim, ..Geometry
 using LinearAlgebra
 
+# define some utility functions 
+right(t::OpticSim.Geometry.Transform{<:Real}) = normalize(Vec3(t[1,1], t[2,1], t[3,1]))
+up(t::OpticSim.Geometry.Transform{<:Real}) = normalize(Vec3(t[1,2], t[2,2], t[3,2]))
+forward(t::OpticSim.Geometry.Transform{<:Real}) = normalize(Vec3(t[1,3], t[2,3], t[3,3]))
+OpticSim.origin(t::OpticSim.Geometry.Transform{<:Real}) = Vec3(t[1,4], t[2,4], t[3,4])
+
 # defining name placeholders to override in nested modules
-generate() = 0 
-export generate
+
+"""
+    generate(???)
+
+[TODO]
+"""
+generate() = 0
+
+"""
+    visual_size(???)
+
+[TODO]
+"""
 visual_size() = 0
-export visual_size
-apply() = 0
-export apply
 
-# define some utility functions 
-right(t::OpticSim.Geometry.Transform{T}) where {T<:Real} = normalize(Vec3(t[1,1], t[2,1], t[3,1]))
-up(t::OpticSim.Geometry.Transform{T}) where {T<:Real} = normalize(Vec3(t[1,2], t[2,2], t[3,2]))
-forward(t::OpticSim.Geometry.Transform{T}) where {T<:Real} = normalize(Vec3(t[1,3], t[2,3], t[3,3]))
-OpticSim.origin(t::OpticSim.Geometry.Transform{T}) where {T<:Real} = Vec3(t[1,4], t[2,4], t[3,4])
-export right, up, forward
+"""
+    apply(???)
+
+[TODO] Returns ray power
+"""
+apply() = 0
 
 include("Spectrum.jl")
 include("Directions.jl")
 include("Origins.jl")
 include("AngularPower.jl")
 include("Sources.jl")
 
-# exporting stuff from the Emitters module
-export Spectrum, Directions, Origins, AngularPower, Sources
-
 end # module Emitters
 
 export Emitters