Add docstring for findAxis function (#107)

* Add docstring for findAxis function

* Add available axis descriptors to docstrings.

* Add docstring for Axes submodule

* Add internal docstring for get_descriptor

Project.toml

@@ -12,6 +12,7 @@ Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 DiskArrayTools = "fcd2136c-9f69-4db6-97e5-f31981721d63"
 DiskArrays = "3c3547ce-8d99-4f5e-a174-61eb10b00ae3"
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 Glob = "c27321d9-0574-5035-807b-f59d2c89b15c"
 Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
@@ -37,6 +38,7 @@ DataFrames = "0.19, 0.20, 0.21, 0.22, 1.0"
 DataStructures = "0.17, 0.18"
 DiskArrayTools = "0.1"
 DiskArrays = "0.3"
+DocStringExtensions = "0.8"
 FFTW = "1"
 Glob = "1.3"
 Interpolations = "0.12, 0.13"

src/Cubes/Axes.jl

@@ -201,6 +201,13 @@ end
 
 const VecOrTuple{S} = Union{Vector{<:S},Tuple{Vararg{<:S}}} where {S}
 
+"""
+# Internal 
+    get_descriptor(a)
+
+Get the descriptor of an Axis. 
+This is used to dispatch on the descriptor. 
+"""
 get_descriptor(a::String) = ByName(a)
 get_descriptor(a::Symbol) = ByName(String(a))
 get_descriptor(a::CubeAxis) = ByValue(a)
@@ -285,15 +292,25 @@ function getOutAxis(desc::Tuple{ByInference}, axlist, incubes, pargs, f)
     end
     return (outaxes...,)
 end
+
 """
-    getAxis(desc::String, c)
+    getAxis(desc, c)
 
-Given the string of an axis name and a cube, returns this axis of the cube.
+Given an Axis description and a cube, returns the corresponding axis of the cube.
+The Axis description can be:
+  - the name as a string or symbol.
+  - an Axis object
 """
 getAxis(desc, c) = getAxis(desc, caxes(c))
 getAxis(desc::ByValue, axlist::Vector{T}) where {T<:CubeAxis} = desc.v
 
-"Fallback method"
+"""
+    findAxis(desc, c)
+Given an Axis description and a cube return the index of the Axis.
+The Axis description can be:
+  - the name as a string or symbol.
+  - an Axis object
+"""
 findAxis(desc, c) = findAxis(desc, caxes(c))
 findAxis(a, axlist::VecOrTuple{CubeAxis}) = findAxis(get_descriptor(a), axlist)
 

src/Cubes/Cubes.jl

@@ -12,6 +12,7 @@ using ..YAXArrays: workdir, YAXDefaults
 using YAXArrayBase: YAXArrayBase, iscompressed, dimnames, iscontdimval
 import YAXArrayBase: getattributes, iscontdim, dimnames, dimvals, getdata
 using DiskArrayTools: CFDiskArray
+using DocStringExtensions
 
 export concatenatecubes, caxes, subsetcube, readcubedata, renameaxis!, YAXArray
 
@@ -39,6 +40,13 @@ using .Axes:
     renameaxis,
     axcopy
 
+    """
+    The `Axes` module handles the Axes of a data cube. 
+    It provides the following exports:
+    
+    $(EXPORTS)
+    """
+    Axes
 mutable struct CleanMe
     path::String
     persist::Bool