Merge pull request #553 from LCSB-BioCore/mk-explain-ko-mod

explain the multi-gene knockouts better

src/analysis/modifications/knockout.jl

@@ -2,7 +2,19 @@
     knockout(gene_ids::Vector{String})
 
 A modification that zeroes the bounds of all reactions that would be knocked
-out by the specified genes (effectively disables the reactions).
+out by the combination of specified genes (effectively disabling the
+reactions).
+
+A slightly counter-intuitive behavior may occur if knocking out multiple genes:
+Because this only changes the reaction bounds, multiple gene knockouts _must_
+be specified in a single call to [`knockout`](@ref), because the modifications
+have no way to remember which genes are already knocked out and which not.
+
+In turn, having a reaction that can be catalyzed either by Gene1 or by Gene2,
+specifying `modifications = [knockout(["Gene1", "Gene2"])]` does indeed disable
+the reaction, but `modifications = [knockout("Gene1"), knockout("Gene2")]` does
+_not_ disable the reaction (although reactions that depend either only on Gene1
+or only on Gene2 are disabled).
 """
 knockout(gene_ids::Vector{String}) =
     (model, optmodel) -> _do_knockout(model, optmodel, gene_ids)