Add detailed docs for the structs returned by various functions.

src/dti_tck.jl

@@ -1,7 +1,7 @@
 
 import Base.show
 
-""" Models a DTI TCK file. """
+""" Models a DTI TCK file. The `header` field contains a dictionary with the header fields, which can be anything a software decides to put there. The `tracks` fields contains a vector of [`DtiTrack`](@ref) structs. """
 struct DtiTck
     header::Dict{String, String}
     tracks::Array{DtiTrack,1}

src/dti_trk.jl

@@ -33,14 +33,15 @@ struct DtiTrkHeader
 end
 
 
-""" Models a single track for a TRK file. """
+""" Models a single track. The field `point_coords` contains an nx3 matrix of point coordinates. The `point_scalars` vector contains zero or more scalar values for each point of the track. The `track_properties` vector contains zero or more scalar values for the whole track. See the corresponding header for interpretation of `point_scalars` and `track_properties`."""
 struct DtiTrack
     point_coords::Array{Float64,2}
     point_scalars::Array{Float64,1}
     track_properties::Array{Float64,1}
 end
 
-""" Models a DTI TRK file. """
+
+""" Models a DTI TRK file. The `header` field contains a [`DtiTrkHeader`](@ref) struct. The `tracks` fields contains a vector of [`DtiTrack`](@ref) structs. """
 struct DtiTrk
     header::DtiTrkHeader
     tracks::Array{DtiTrack,1}

src/fs_annot.jl

@@ -2,7 +2,7 @@
 
 import Base.show
 
-""" Models the brain region table included in an [`FsAnnot`](@ref) FreeSurfer annotation. Each entry describes a brain region. """
+""" Models the brain region table included in an [`FsAnnot`](@ref) FreeSurfer annotation. Each entry describes a brain region, which has a running numerical id, a name, a display color (r,g,b), and a unique integer label (computed from the color code) which is used in the corresponding [`FsAnnot`](@ref) to identify the region of a vertex. """
 struct ColorTable
     id::Array{Int32, 1} # region index, not really needed. The label is relevant, see below.
     name::Array{AbstractString, 1}
@@ -14,7 +14,7 @@ struct ColorTable
 end
 
 
-""" Models a FreeSurfer brain surface parcellation from an annot file. """
+""" Models a FreeSurfer brain surface parcellation from an annot file. This is the result of applying a brain atlas (like Desikan-Killiani) to a subject. The `vertex_indices` are the 0-based indices used in FreeSurfer and should be ignored. The `vertex_labels` field contains the mesh vertices in order, and assigns to each vertex a brain region using the `label` field (not the `id` field!) from the `colortable`. The field `colortable` contains a [`ColorTable`](@ref) struct that describes the brain regions. """
 struct FsAnnot
     vertex_indices::Array{Int32,1} # 0-based indices, not really needed.
     vertex_labels::Array{Int32,1}

src/fs_curv.jl

@@ -14,7 +14,7 @@ struct CurvHeader
 end
 
 
-""" Models the structure of a file in Curv format. """
+""" Models the structure of a file in Curv format. The `header` field contains a [`CurvHeader`](@ref), the `data` field is a Float32 vector of per-vertex values. The values appear in the same order as the the vertices in the corresponding brain mesh (surf) file."""
 struct Curv
     header::CurvHeader
     data::Array{Float32, 1}

src/fs_mgh.jl

@@ -4,7 +4,7 @@ using CodecZlib
 using Printf
 using LinearAlgebra
 
-""" Models the header of a FreeSurfer brain volume file in MGH or MGZ format."""
+""" Models the header of a FreeSurfer brain volume file in MGH or MGZ format. The data in the `delta`, `mdc` and `p_xyz_c` fields must be used only if `is_ras_good` is 1, otherwise their contents is random."""
 struct MghHeader
     mgh_version::Int32
     ndim1::Int32   # size of first dimension.
@@ -22,7 +22,7 @@ end
 """ Alternate MghHeader constructor that does not require valid RAS information. """
 MghHeader(ndim1::Integer, ndim2::Integer, ndim3::Integer, ndim4::Integer, dtype::Integer) = MghHeader(1, ndim1, ndim2, ndim3, ndim4, dtype, 0, Int16(0), zeros(Float32, 3), Base.reshape(zeros(Float32, 9), (3, 3)), zeros(Float32, 3))
 
-""" Models a FreeSurfer brain volume file in MGH or MGZ format."""
+""" Models a FreeSurfer brain volume file in MGH or MGZ format. The field `header` is an [`MghHeader`](@ref) struct, and the `data` field is a 4-dimensional numerical array. The exact data type of the `data` array depends on the file contents."""
 struct Mgh{T<:Number}
     header::MghHeader
     data::AbstractArray{T}
@@ -122,7 +122,7 @@ end
 """
     mgh_vox2ras(mgh::Mgh)
 
-Compute the VOX2RAS matrix for an Mgh instance. Requires valid RAS header data.
+Compute the vox2ras matrix for an [`Mgh`](@ref) instance. Requires valid RAS header data. The vox2ras matrix can be used to compute the `x`, `y`, `z` RAS coordinates of a voxel based on its `i`, `j` and `k` indices in the first three dimensions of the volume. Its inverse, the ras2vox matrix, can be used to compute the indices of the voxel that occupies a point in space given by its `x`, `y`, `z` RAS coordinates.
 
 # Examples
 ```julia-repl

src/fs_surface.jl

@@ -4,7 +4,7 @@ import Base.show
 
 const TRIS_MAGIC_FILE_TYPE_NUMBER = 16777214
 
-""" Models the header section of a file in FreeSurfer Surface format. The files are big endian. """
+""" Models the header section of a file in FreeSurfer Surface format. The files are big endian. This header can usually be ignored. """
 struct FsSurfaceHeader
     magic_b1::UInt8
     magic_b2::UInt8
@@ -21,7 +21,7 @@ num_vertices(sh::FsSurfaceHeader) = sh.num_vertices
 num_faces(sh::FsSurfaceHeader) = sh.num_faces
 
 
-""" Models a trimesh. Vertices are defined by their xyz coordinates, and faces are given as indices into the vertex array. """
+""" Models a trimesh. Vertices are defined by their xyz coordinates and contained in the `vertices` field as an `n*3` matrix, and faces are given as indices into the vertex array in the `faces` field. """
 struct BrainMesh
     vertices::Array{Float32, 2}   # vertex xyz coords
     faces::Array{Int32, 2}        # indices of the 3 vertices forming the face / polygon / triangle
@@ -34,7 +34,7 @@ num_vertices(bm::BrainMesh) = Base.length(bm.vertices) / 3
 num_faces(bm::BrainMesh) = Base.length(bm.faces) / 3
 Base.show(io::IO, x::BrainMesh) = @printf("Brain mesh with %d vertices and %d faces.\n", num_vertices(x), num_faces(x))
 
-""" Models FreeSurfer Surface file. """
+""" Models FreeSurfer Surface file. The `header` field is an [`FsSurfaceHeader`](@ref) struct that can usually be ignored, the `mesh` field is a [`BrainMesh`](@ref) struct. """
 struct FsSurface
     header::FsSurfaceHeader
     mesh::BrainMesh