Add more docstrings with signatures (issue #22)

src/particle.jl

@@ -1,6 +1,10 @@
 abstract type AbstractParticle{T,Dim} end
 
-"A homogenous particle with any properties and shape"
+"""
+    Particle(medium::PhysicalProperties, shape::Shape)
+
+Create particle with inner medium and shape (types and dimension must agree).
+"""
 struct Particle{T<:AbstractFloat,Dim,P<:PhysicalProperties,S<:Shape} <: AbstractParticle{T,Dim}
     medium::P
     shape::S
@@ -11,7 +15,9 @@ struct Particle{T<:AbstractFloat,Dim,P<:PhysicalProperties,S<:Shape} <: Abstract
 end
 
 """
-A particle within another particle, both with the same type of shape and origin. Produces a scalar (1D) field in arbitrary dimensions.
+    CapsuleParticle(outer::Particle, inner::Particle)
+
+A particle within another particle, both with the same shape type and origin.
 """
 struct CapsuleParticle{T<:AbstractFloat,Dim,P<:PhysicalProperties,S<:Shape} <: AbstractParticle{T,Dim}
     outer::Particle{T,Dim,P,S}
@@ -77,10 +83,11 @@ function isequal(p1::Particle, p2::Particle)
 end
 
 """
-Returns true if medium and shape of particles are the same, ignoring the origin
-of shape
+    congruent(p1::AbstractParticle, p2::AbstractParticle)::Bool
+
+Returns true if medium and shape of particles are the same, ignoring origin, false otherwise.
 """
-congruent(p1::AbstractParticle, p2::AbstractParticle) = false
+congruent(p1::AbstractParticle, p2::AbstractParticle) = false # false by default, overload in specific examples
 
 function congruent(p1::Particle, p2::Particle)
     p1.medium == p2.medium &&

src/physics/acoustics/acoustics.jl

@@ -1,6 +1,10 @@
 """
-Physical properties for a homogenous isotropic acoustic medium. Produces a
-scalar (1D) field in arbitrary dimensions.
+    Acoustic{T<:AbstractFloat,Dim}(ρ::T, c::Complex{T})
+    Acoustic(ρ::T, c::Union{T,Complex{AbstractFloat}}, Dim::Integer)
+
+Physical properties for a homogenous isotropic acoustic medium with wavespeed (c) and density (ρ)
+
+Simulations in this medium produce scalar (1D) fields in Dim dimensions.
 """
 struct Acoustic{T,Dim} <: PhysicalProperties{T,Dim,1}
     ρ::T # Density

src/shapes/circle.jl

@@ -1,4 +1,8 @@
-"Shape where boundary is a fixed distance from the origin"
+"""
+    Circle(origin, radius)
+
+2D [`Shape`](@ref) where boundary is a fixed distance from the origin
+"""
 struct Circle{T} <: Shape{T,2}
     origin::SVector{2,T}
     radius::T

src/shapes/rectangle.jl

@@ -1,6 +1,8 @@
 """
-Shape with 4 right-angles and axis aligned sides, defined by width and height.
-Note: the origin is in the center of the rectangle.
+    Rectangle(origin::AbstractVector{T}, width::T, Height::T)
+    Rectangle(bottomleft::AbstractVector{T}, topright::AbstractVector{T})
+
+2D [`Shape`](@ref) with axis aligned sides, defined by width, height and origin (at the center).
 """
 struct Rectangle{T} <: Shape{T,2}
     origin::SVector{2,T}

src/shapes/shapes.jl

@@ -1,16 +1,21 @@
 """
-Abstract idea which defines the external boundary of object. Two objects have
-the same shape if they are congruence.
+Abstract idea which defines the external boundary of object.
 """
 abstract type Shape{T<:AbstractFloat,Dim} end
 
-"Origin of a shape, typically the center"
+"""
+    origin(shape::Shape)::SVector
+
+Origin of shape, typically the center
+"""
 origin(shape::Shape) = shape.origin
 
-# For two different shapes, the answer is false. For concrete types this
-# function must be overloaded
-"Returns true if two shapes are the same, ignoring their origin."
-congruent(s1::Shape, s2::Shape) = false
+"""
+    congruent(p1::Shape, p2::Shape)::Bool
+
+True if shapes are the same but in different positions (origins), standard mathematical definition.
+"""
+congruent(s1::Shape, s2::Shape) = false # false by default, overload in specific examples
 
 "Generic helper function which tests if boundary coordinate is between 0 and 1"
 function check_boundary_coord_range(t)
@@ -47,20 +52,37 @@ function bounding_rectangle(shapes::Vector{S}) where S<:Shape
 end
 
 # Docstrings
-"Name of a shape"
+"""
+    name(shape::Shape)::String
+
+Name of a shape
+"""
 name
 
-"The radius of a circle which contains the shape."
+"""
+    outer_radius(shape::Shape{T})::T
+
+The radius of a circle which completely contains the shape
+"""
 outer_radius
 
-"Volume of a shape"
+"""
+    volume(shape::Shape{T})::T
+
+Volume of a shape
+"""
 volume
 
-"Returns whether an object (2nd arg) is inside a shape (1st arg)"
+"""
+    volume(shape1::Shape, shape2::Shape)::Bool
+
+True if shape2 is completely contained within shape1
+"""
 inside
 
 """
-Returns Dim functions which accept a boundary coordinate (0<=t<=1)to trace outer
-boundary of shape.
+    volume(shape::Shape)::NTuple{Function,Dim)
+
+Returns Tuple of Dim Functions which define outer boundary of shape when given boundary coordinate t∈[0,1]
 """
 boundary_functions