Improve Documentation of Non-Trivial Operations

[baierd]

Some operations in SMTLib2, for example Integer modulo() and BV smodulo() (signed modulo), behave differently. Our documentation does not reflect this properly or fails to explain the differences in a well-understandable way. Additionally, we could update the documentation of some operations that are not well understandable. We should take a closer look at our public API documentation and update it accordingly.

Examples:

• Integer modulo
• BV smodulo
• BV remainder
• BV division
• Integer modularCongruence
• Numeral division

[PhilippWendler]

As one example of what I see that could be improved, I looked at the current JavaDoc of Integer modulo:

java-smt/src/org/sosy_lab/java_smt/api/IntegerFormulaManager.java

Lines 29 to 46 in fed0e55

	* Create a formula representing the modulo of two operands according to Boute's Euclidean
	* definition. The quotient (div numerator denominator) of the internal modulo calculation is
	* floored for positive denominators and rounded up for negative denominators.
	*
	* <p>If the denominator evaluates to zero (modulo-by-zero), either directly as value or
	* indirectly via an additional constraint, then the solver is allowed to choose an arbitrary
	* value for the result of the modulo operation (cf. SMTLIB standard for the division operator in
	* Ints or Reals theory).
	*
	* <p>Examples:
	*
	* <ul>
	* <li>10 % 5 == 0
	* <li>10 % 3 == 1
	* <li>10 % (-3) == 1
	* <li>-10 % 5 == 0
	* <li>-10 % 3 == 2
	* <li>-10 % (-3) == 2

My thoughts:

• Is there a link for this "Boute's Euclidean" definition? It does not ring a bell for me and I would have to google it.
• What is "the internal modulo calculation" that is mentioned? Is this relevant for users? This part might be better rewritten.
• There are these formulas like n = k*d + r that specify exactly which condition the result fulfills. Can't you write something like that here, i.e., an actual formal definition? Something like "modulo(n, d) == r holds iff ...".
• I would generally avoid % in the examples. This may still be ok here, but why suddenly use an operator symbol in the examples that does not appear anywhere else in the text and is therefore not defined at all? And with smodulo/remainder it really causes confusion. The examples should simply use the function name, i.e., modulo(10, 5) == 0 etc.
• And is it true for integer modulo that it is the same or similar or explicitly different to the % operator in common programming languages? Then it would be helpful for users to discuss this. Something like "Note that this function implements the same semantics as the % operator in programming languages like C or Java (with the obvious exception of applying it to unbounded integers instead of bitvectors)."
• "then the solver is allowed to choose an arbitrary value for the result of the modulo operation": What does that mean exactly? According to the SMTLib standard, is the result nondeterministic, i.e., all values are possible? Or is the result always a specific value, but the value differs depending on the solver? Or is both permitted by the standard? These are all relevant different cases and it should be clarified which of them applies.
• It would be best to link to the (relevant section of) the SMTLib standard.
• For those theories were both remainder and modulo are defined, an explicit cross-reference and discussion of the differences would be good.