docstring_template.txt

"""
# Sample docstring following the Julia conventions, see:
# https://docs.julialang.org/en/v1/manual/documentation/index.html
# for reference.
# Each point, e.g. 1) Has general guidelines, please read them
# See full example in the bottom

1) Function signature
- always with 4 space indent:
    function_name(x, y=1)
- Use simplified form, omitting type i.e. function_name(x::Float64)
should be function_name(x). Include type if really important
- brackets are used for optional arguments without default value i.e.:
f(x[, y])
- in case of many keyword arguments write: f(x; <keyword arguments>)
and add <keyword arguments> in 4)

2) Description
- one-line sentence
- imperative: "Do this", "Return that" instead of "Returns the length..."
- lines ends with period "."
- in complex cases, break into several one-line sentences
- add `` around arguments. i.e. `x or `x::Integer=1`

3) Don't repeat yourself
- Don't start documentation with "The function bar...": go straight to the point.
- Only mention arugment types if not stated explicitely in function signature.

4) Argument list
- Only include if really really necessary
- If necessary, it should be stated with #Arguments, and then list items with
"-". The list should mention the types and default values (if any) of the
arguments. Example:

# Arguments
- `n::Integer`: the number of elements to compute.
- `dim::Integer=1`: the dimensions along which to perform the computation.

5) Hints to related functions (if necessary)
Sometimes there are functions of related functionality.
Increase discoverability by providing a short list of these under "See also":

See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref)

6) Example
- If untestable write with ```julia, otherwise:
```jldoctest
julia> f(1, 2)
2×2 Array{Int64,2}:
 1  2
 3  4
julia> ...
```

7) Linebreaks after 92 charecters

8) Implementation section
- Provide information allowing custom types to implement the function
in an # Implementation section.
- Meant for developpers


A) TO-DO
- if you need to write To-Do's do it just after function definition
with #=, =#:

function_name(x, y)
#=
TO-DO
specify argument types
=#



EXAMPLE DOCSTRING WITH ALL OPTIONS BELOW (omit #Argumnts, #Implementation
and "See aslo" if needed)
"""


# EXAMPLE DOCSTRING:
"""
    ellipsoid2xyz(lat::Array{Number,N}, lon::Array{Number,N},
                  height::Array{Number,N}, semi_major_axis=6378137.,
                  flattening=1/298.257223563)

Convert ellipsoid coordinates to cartisian coordinates, based on ellipsoidal
latitudes (rad), longitudes (rad) and heights (m).

# Arguments
- `lat::Array{Number,N}`: Ellipsoidal latitudes, either single number or array
- `lon::Array{Number,N}`: Ellipsoidal longitudes, either single number or array
- `height::Array{Number,N}`:   Ellipsoidal heights, either single number or array
- `semi_major_axis::Number=6378137.`: reference ellipsoid major semi-axis (m); default GRS80
- `flattening::Number=1/298.257223563`: reference ellipsoid eccentricity computed based on flattening; default GRS80


See also: [`f!`](@ref), [`g`](@ref), [`function`](@ref)

# Examples:
```jldoctest
julia> a = 10; e2 = 2; h = [.2, .1, .6];
julia> lat = [pi/4, 3*pi, pi/6]; lon = [pi/2, pi/4, pi/8];
julia> x, y, z = ellipsoid2xyz(lat, lon, h, a, e2);
julia> x
3-element Array{Float64,1}:
  2.90566636126016e-8
 -7.14177848998413
 11.795229079383331
julia> y
3-element Array{Float64,1}:
  4.7453132826267916e8
 -7.141778489984129
  4.885743855978092
julia> z
3-element Array{Float64,1}:
 -4.7453132797983634e8
 -3.637200993467639e-15
 -6.771067811865474
```

# Implementation
Overwrite the X functionality in the case Y.
Change argument x::Number to x::String if used in case Z.
"""
function ellipsoid2xyz(lat, lon, height, semi_major_axis=6378137.,
                       flattening=1/298.257223563)
    #=
    TO-DO
    specify arugment types for lat, lon, height.
    =#
    e2 = flattening * (2 - flattening)
    v = semi_major_axis./sqrt.(ones(3)-e2*sin.(lat).*sin.(lat))
    x=(v+height).*cos.(lat).*cos.(lon)
    y=(v+height).*cos.(lat).*sin.(lon)
    z=(v.*(1-e2)+height).*sin.(lat)
    return x, y, z
end