Documentation fixes

Signed-off-by: Christoph M. Wintersteiger <cwinter@microsoft.com>

doc/mk_api_doc.py

@@ -27,6 +27,10 @@ try:
     shutil.copyfile('website.dox', 'tmp/website.dox')
     shutil.copyfile('../src/api/python/z3.py', 'tmp/z3py.py')
     cleanup_API('../src/api/z3_api.h', 'tmp/z3_api.h')
+    cleanup_API('../src/api/z3_algebraic.h', 'tmp/z3_algebraic.h')
+    cleanup_API('../src/api/z3_polynomial.h', 'tmp/z3_polynomial.h')
+    cleanup_API('../src/api/z3_rcf.h', 'tmp/z3_rcf.h')
+    cleanup_API('../src/api/z3_interp.h', 'tmp/z3_interp.h')
     
     print "Removed annotations from z3_api.h."
     try:
@@ -38,6 +42,10 @@ try:
         exit(1)
     print "Generated C and .NET API documentation."
     os.remove('tmp/z3_api.h')
+    os.remove('tmp/z3_algebraic.h')
+    os.remove('tmp/z3_polynomial.h')
+    os.remove('tmp/z3_rcf.h')
+    os.remove('tmp/z3_interp.h')
     print "Removed temporary file z3_api.h."
     os.remove('tmp/website.dox')	
     print "Removed temporary file website.dox"

doc/z3api.dox

@@ -363,7 +363,7 @@ TYPEDEF_HIDES_STRUCT   = NO
 # 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0,
 # corresponding to a cache size of 2^16 = 65536 symbols.
 
-SYMBOL_CACHE_SIZE      = 0
+# SYMBOL_CACHE_SIZE      = 0
 
 # Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be
 # set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given
@@ -708,7 +708,11 @@ INPUT_ENCODING         = UTF-8
 # *.f90 *.f *.for *.vhd *.vhdl
 
 FILE_PATTERNS          = website.dox \
-                         z3_api.h \
+			 z3_api.h \
+			 z3_algebraic.h \
+			 z3_polynomial.h \
+			 z3_rcf.h \
+			 z3_interp.h \
                          z3++.h \
                          z3py.py \
                          ApplyResult.cs \
@@ -1477,13 +1481,13 @@ XML_OUTPUT             = xml
 # which can be used by a validating XML parser to check the
 # syntax of the XML files.
 
-XML_SCHEMA             =
+# XML_SCHEMA             =
 
 # The XML_DTD tag can be used to specify an XML DTD,
 # which can be used by a validating XML parser to check the
 # syntax of the XML files.
 
-XML_DTD                =
+# XML_DTD                =
 
 # If the XML_PROGRAMLISTING tag is set to YES Doxygen will
 # dump the program listings (including syntax highlighting
@@ -1699,7 +1703,7 @@ DOT_NUM_THREADS        = 0
 # the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the
 # directory containing the font.
 
-DOT_FONTNAME           = FreeSans
+# DOT_FONTNAME           = FreeSans
 
 # The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs.
 # The default size is 10pt.

src/api/java/AST.java

@@ -24,28 +24,12 @@ import com.microsoft.z3.enumerations.Z3_ast_kind;
  **/
 public class AST extends Z3Object
 {
-    /**
-     * Comparison operator. <param name="a">An AST</param> <param name="b">An
-     * AST</param>
-     * 
-     * @return True if <paramref name="a"/> and <paramref name="b"/> are from
-     *         the same context and represent the same sort; false otherwise.
-     **/
-    /* Overloaded operators are not translated. */
-
-    /**
-     * Comparison operator. <param name="a">An AST</param> <param name="b">An
-     * AST</param>
-     * 
-     * @return True if <paramref name="a"/> and <paramref name="b"/> are not
-     *         from the same context or represent different sorts; false
-     *         otherwise.
-     **/
     /* Overloaded operators are not translated. */
 
     /**
      * Object comparison.
-     **/
+     * <param name="o">another AST</param>
+     **/    
     public boolean equals(Object o)
     {
         AST casted = null;

src/api/java/Expr.java

@@ -40,7 +40,7 @@ public class Expr extends AST
 	/**
 	 * Returns a simplified version of the expression 
 	 * A set of
-	 * parameters <param name="p" /> to configure the simplifier 
+	 * parameters <param name="p">a Params object</param> to configure the simplifier 
 	 * <seealso cref="Context.SimplifyHelp"/>
 	 **/
 	public Expr simplify(Params p) throws Z3Exception

src/api/java/Global.java

@@ -50,8 +50,7 @@ public final class Global
     /**
      * Get a global (or module) parameter.     
      * <remarks>               
-     * Returns null if the parameter <param name="id"/> does not exist.
-     * The caller must invoke #Z3_global_param_del_value to delete the value returned at \c param_value.
+     * Returns null if the parameter <param name="id">parameter id</param> does not exist.     
      * This function cannot be invoked simultaneously from different threads without synchronization.
      * The result string stored in param_value is stored in a shared location.
      * </remarks>
@@ -70,7 +69,7 @@ public final class Global
      * <remarks>
      * This command will not affect already created objects (such as tactics and solvers)
      * </remarks>
-     * @seealso SetParameter
+     * <seealso cref="SetParameter"/>
      **/
     public static void resetParameters()
     {

src/api/java/Sort.java

@@ -25,27 +25,10 @@ import com.microsoft.z3.enumerations.Z3_sort_kind;
  **/
 public class Sort extends AST
 {
-    /**
-     * Comparison operator. <param name="a">A Sort</param> <param name="b">A
-     * Sort</param>
-     * 
-     * @return True if <paramref name="a"/> and <paramref name="b"/> are from
-     *         the same context and represent the same sort; false otherwise.
-     **/
     /* Overloaded operators are not translated. */
 
     /**
-     * Comparison operator. <param name="a">A Sort</param> <param name="b">A
-     * Sort</param>
-     * 
-     * @return True if <paramref name="a"/> and <paramref name="b"/> are not
-     *         from the same context or represent different sorts; false
-     *         otherwise.
-     **/
-    /* Overloaded operators are not translated. */
-
-    /**
-     * Equality operator for objects of type Sort. <param name="o"></param>
+     * Equality operator for objects of type Sort. <param name="o"/>
      * 
      * @return
      **/

src/api/z3_algebraic.h

@@ -23,7 +23,19 @@ Notes:
 
 #ifdef __cplusplus
 extern "C" {
-#endif // __cplusplus
+#endif // __cplusplus    
+
+    /**
+    \defgroup capi C API
+
+    */
+
+    /*@{*/
+
+    /**
+    @name Algebraic Numbers API
+    */
+    /*@{*/
 
     /**
        \brief Return Z3_TRUE if \c can be used as value in the Z3 real algebraic
@@ -218,6 +230,8 @@ extern "C" {
     */
     int Z3_API Z3_algebraic_eval(__in Z3_context c, __in Z3_ast p, __in unsigned n, __in Z3_ast a[]);    
 
+    /*@}*/
+    /*@}*/
 
 #ifdef __cplusplus
 };

src/api/z3_api.h

@@ -771,7 +771,6 @@ typedef enum
 
         The premises of the rules is a sequence of clauses.
         The first clause argument is the main clause of the rule.
-        One literal from the second, third, .. clause is resolved
         with a literal from the first (main) clause.
 
         Premises of the rules are of the form
@@ -1143,8 +1142,8 @@ typedef enum {
    - Z3_FILE_ACCESS_ERRROR: A file could not be accessed.
    - Z3_INVALID_USAGE:   API call is invalid in the current state.
    - Z3_INTERNAL_FATAL: An error internal to Z3 occurred.
-   - Z3_DEC_REF_ERROR: Trying to decrement the reference counter of an AST that was deleted or the reference counter was not initialized\mlonly.\endmlonly\conly with #Z3_inc_ref.
-   - Z3_EXCEPTION:     Internal Z3 exception. Additional details can be retrieved using \mlonly #Z3_get_error_msg. \endmlonly \conly #Z3_get_error_msg_ex.
+   - Z3_DEC_REF_ERROR: Trying to decrement the reference counter of an AST that was deleted or the reference counter was not initialized \mlonly.\endmlonly \conly with #Z3_inc_ref.
+   - Z3_EXCEPTION:     Internal Z3 exception. Additional details can be retrieved using #Z3_get_error_msg.
 */
 typedef enum
 {
@@ -1287,8 +1286,6 @@ extern "C" {
 
        \sa Z3_global_param_set
 
-       The caller must invoke #Z3_global_param_del_value to delete the value returned at \c param_value.
-
        \remark This function cannot be invoked simultaneously from different threads without synchronization.
        The result string stored in param_value is stored in shared location.
 

src/api/z3_interp.h

@@ -24,7 +24,14 @@ extern "C" {
 #endif // __cplusplus
 
     /**
-        @name Interpolation
+    \defgroup capi C API
+
+    */
+
+    /*@{*/
+
+    /**
+        @name Interpolation API
         */
     /*@{*/
 
@@ -184,6 +191,8 @@ extern "C" {
        \param cnsts Returns sequence of formulas (do not free)
        \param parents Returns the parents vector (or NULL for sequence)
        \param error Returns an error message in case of failure (do not free the string)
+       \param num_theory Number of theory terms
+       \param theory Theory terms
 
        Returns true on success.
 
@@ -232,6 +241,8 @@ extern "C" {
         \param parents The parents vector (or NULL for sequence)
         \param interps The interpolant to check
         \param error Returns an error message if interpolant incorrect (do not free the string)
+        \param num_theory Number of theory terms
+        \param theory Theory terms
 
         Return value is Z3_L_TRUE if interpolant is verified, Z3_L_FALSE if
         incorrect, and Z3_L_UNDEF if unknown.
@@ -258,6 +269,8 @@ extern "C" {
         \param cnsts Array of constraints
         \param parents The parents vector (or NULL for sequence)
         \param filename The file name to write
+        \param num_theory Number of theory terms
+        \param theory Theory terms
 
         def_API('Z3_write_interpolation_problem', VOID, (_in(CONTEXT), _in(UINT), _in_array(1, AST), _in_array(1, UINT), _in(STRING), _in(UINT), _in_array(5, AST)))
         */
@@ -270,6 +283,9 @@ extern "C" {
                                                 __in unsigned num_theory,
                                                 __in_ecount(num_theory) Z3_ast theory[]);
 
+    /*@}*/
+    /*@}*/
+
 #ifdef __cplusplus
 };
 #endif // __cplusplus

src/api/z3_polynomial.h

@@ -24,6 +24,19 @@ Notes:
 extern "C" {
 #endif // __cplusplus
 
+    /**
+    \defgroup capi C API
+
+    */
+
+    /*@{*/
+
+
+    /**
+    @name Polynomials API
+    */
+    /*@{*/
+
     /**
        \brief Return the nonzero subresultants of \c p and \c q with respect to the "variable" \c x.
        
@@ -38,6 +51,9 @@ extern "C" {
     Z3_ast_vector Z3_API Z3_polynomial_subresultants(__in Z3_context c, __in Z3_ast p, __in Z3_ast q, __in Z3_ast x);
 
 
+    /*@}*/
+    /*@}*/
+
 #ifdef __cplusplus
 };
 #endif // __cplusplus

src/api/z3_rcf.h

@@ -25,6 +25,18 @@ Notes:
 #ifdef __cplusplus
 extern "C" {
 #endif // __cplusplus
+    
+    /**
+    \defgroup capi C API
+
+    */
+
+    /*@{*/
+
+    /**
+    @name Real Closed Fields API
+    */
+    /*@{*/
 
     /**
        \brief Delete a RCF numeral created using the RCF API.
@@ -192,6 +204,9 @@ extern "C" {
     */
     void Z3_API Z3_rcf_get_numerator_denominator(__in Z3_context c, __in Z3_rcf_num a, __out Z3_rcf_num * n, __out Z3_rcf_num * d);
 
+    /*@}*/
+    /*@}*/
+
 #ifdef __cplusplus
 };
 #endif // __cplusplus