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.

[baierd]

Thank you for your input!

I've extended the discussed methods JavaDoc with many of your thoughts.

Some are not really applicable however:

• "And is it true for integer modulo that it is the same or similar or explicitly different to the % operator in common programming languages?" What is a common programming language? Also, i would argue that the user has to check whatever is applicable here anyways.
• "It would be best to link to the (relevant section of) the SMTLib standard." I 100% agree. But thats not possible, as the standard is... lets say a little scattered. Most information can be found by simply going to the standard and checking the page of the appropriate theory. I don't see a benefit in linking that.
• "For those theories were both remainder and modulo are defined, an explicit cross-reference and discussion of the differences would be good." While i agree in general, we explicitly state the definitions and the differences are a result of those. A user has to understand what the function is doing anyways. Also, we might actually make a mistake in describing the differences.

Note: we currently have not only the most explanation for those functions out of any solver or library, but exceed the standard itself!