document the functions

src/readsbml.jl

 
 const VPtr = Ptr{Cvoid}
 
+"""
+    function readSBML(fn::String)::Model
+
+Read the SBML from a XML file in `fn` and return the contained `Model`.
+"""
 function readSBML(fn::String)::Model
     doc = ccall(sbml(:readSBML), VPtr, (Cstring,), fn)
     try

src/structs.jl

 
+"""
+Part of a measurement unit definition that corresponds to the SBML definition of `Unit`. For example, "per square megahour", Mh^(-2), is written as:
+
+    UnitPart("second", # base unit of time
+             -2, # exponent, says "per square"
+             6, # scale in powers of 10, says "mega"
+             1/3600) # second-to-hour multiplier
+"""
 struct UnitPart
     kind::String
     exponent::Int
@@ -7,6 +15,11 @@ struct UnitPart
     UnitPart(k, e, s, m) = new(k, e, s, m)
 end
 
+"""
+Reaction with stoichiometry that assigns reactants and products their relative
+consumption/production rates, lower/upper bounds (in tuples with unit names),
+and objective coefficient.
+"""
 struct Reaction
     stoichiometry::Dict{String,Float64}
     lb::Tuple{Float64,String}
@@ -15,12 +28,19 @@ struct Reaction
     Reaction(s, l, u, o) = new(s, l, u, o)
 end
 
+"""
+Species metadata -- human-readable name and compartment identifier
+"""
 struct Species
     name::String
     compartment::String
     Species(n, c) = new(n, c)
 end
 
+"""
+Structure that collects the model-related data. Dictionaries are indexed by
+identifiers of the corresponding objects.
+"""
 struct Model
     units::Dict{String,Vector{UnitPart}}
     compartments::Vector{String}

src/utils.jl

-#TODO this will need a sparse version and faster row ID lookup
+"""
+    function getS(m::Model)::Tuple{Vector{String},Vector{String},Matrix{Float64}}
+
+Extract the vector of species (aka metabolite) identifiers, vector of reaction
+identifiers, and the (dense) stoichiometry matrix from an existing `Model`.
+Returns a tuple with these values.
+"""
 function getS(m::Model)::Tuple{Vector{String},Vector{String},Matrix{Float64}}
+    #TODO this will need a sparse version and faster row ID lookup
     rows = [k for k in keys(m.species)] #TODO this too
     cols = [k for k in keys(m.reactions)]
     S = zeros(Float64, length(rows), length(cols))
@@ -10,14 +17,31 @@ function getS(m::Model)::Tuple{Vector{String},Vector{String},Matrix{Float64}}
     return rows, cols, S
 end
 
+"""
+    function getLBs(m::Model)::Vector{Tuple{Float64,String}}
+
+Extract a vector of lower bounds of reaction rates from the model. All bounds
+are accompanied with the unit of the corresponding value (this behavior is
+based on SBML specification).
+"""
 function getLBs(m::Model)::Vector{Tuple{Float64,String}}
     return broadcast(x -> x.lb, values(m.reactions))
 end
 
+"""
+    function getUBs(m::Model)::Vector{Tuple{Float64,String}}
+
+Likewise to `getLBs`, extract the upper bounds.
+"""
 function getUBs(m::Model)::Vector{Tuple{Float64,String}}
     return broadcast(x -> x.ub, values(m.reactions))
 end
 
+"""
+    function getOCs(m::Model)::Vector{Float64}
+
+Extract the vector of objective coefficients of each reaction.
+"""
 function getOCs(m::Model)::Vector{Float64}
     return broadcast(x -> x.oc, values(m.reactions))
 end

src/version.jl

 
-function SBMLVersion()
+"""
+    function SBMLVersion()
+
+Get the version of the used SBML library in Julia version format.
+"""
+function SBMLVersion()::VersionNumber
     VersionNumber(unsafe_string(ccall(sbml(:getLibSBMLDottedVersion), Cstring, ())))
 end