doc: niche model

src/random/structural.jl

@@ -8,7 +8,11 @@ abstract type StructuralModel end
 """
     NicheModel
 
-The niche model of food webs...
+The niche model of food webs is one of the most emblematic food web models.
+Based on a given species richness and *expected* connectance, it generates food
+webs with properties that closely reproduce empirical networks. One particular
+property of the food webs generated with this model is that they are *interval*,
+which is to say that there are not gaps in the diet of species.
 
 ###### References
 

src/random/structural/nichemodel.jl

@@ -1,7 +1,10 @@
 """
     structuralmodel(::Type{NicheModel}, species::Integer=10, connectance::AbstractFloat=0.2)
 
-Generate a food web under the niche model with the given number of species, and an *expected* connectance.
+Generate a food web under the niche model with the given number of species, and
+an *expected* connectance. Note that by the nature of the niche model algorithm,
+only the species richness is guaranteed; there is no guarantee that the
+connectance will be correct.
 
 See [`NicheModel`](@ref) for more information about the niche model.
 """
@@ -46,6 +49,15 @@ end
     @test typeof(N.edges) <: Binary
 end
 
+"""
+    structuralmodel(::Type{NicheModel}, species::Integer=10, edges::Integer=20)
+
+Generate a food web under the niche model with the given number of species, and
+an *expected* numnber of edges. The expected connectance is calculated from the
+number of links.
+
+See [`NicheModel`](@ref) for more information about the niche model.
+"""
 function structuralmodel(::Type{NicheModel}, species::Integer=10, edges::Integer=20)
     @assert species > 0
     @assert (species - 1) < edges < 0.5(species^2)