# specifying typical values

For the purpose of constructing good documentation automatically, it is useful to specify the type of value typically returned by a function or method. For example, the function isModule returns a boolean value, and this is specified when creating the method function with the option TypicalValue as follows.
isModule = method(TypicalValue => Boolean)

Other functions, such as prune, return values of various types, depending on the type of the arguments provided. To install a function f as the handler for prune applied to a matrix, we would normally use the following statement.

prune Matrix := f
To specify that the value typically returned is a matrix (of class Matrix), we replace f by Matrix => f, as follows.
prune Matrix := Matrix => f
Here is the way our code looks.
 i1 : code(prune, Matrix) o1 = -- code for method: prune(Matrix) /usr/share/Macaulay2/Core/modules2.m2:493:64-498:6: --source code: minimalPresentation(Matrix) := prune(Matrix) := Matrix => opts -> (m) -> ( M := source m; if not M.cache.?pruningMap then m = m * (minimalPresentation M).cache.pruningMap; N := target m; if not N.cache.?pruningMap then m = (minimalPresentation N).cache.pruningMap^-1 * m; m)
The information is stored in the hash table typicalValues, and can be recovered like this.
 i2 : typicalValues#(prune,Matrix) o2 = Matrix o2 : Type

Warning: don't imagine that a definition of the form

f = t -> (...)
can be replaced with a declaration of the following form.
f = X => t -> (...)
The difference here is that here we are using simple assignment, rather than installing a method. To document the return type is X in this case, make an entry in typicalValues directly.
f = t -> (...)
typicalValues#f = X