use doxygen

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -Dbreathe_projects.my_project=../build/doxygen/xml -j=auto
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = Flint
 SOURCEDIR     = source
@@ -12,9 +12,12 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+build/doxygen:	$(wildcard ../src/**/*.c)
+	doxygen Doxyfile.in
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+%: Makefile build/doxygen
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/source/ca_field.rst

@@ -93,138 +93,68 @@ For all types, a *type_t* is defined as an array of length one of type
 .. macro:: CA_FIELD_IDEAL_ELEM(K, i)
 
     Assuming that *K* represents a multivariate field, accesses element *i*
-    (indexed from zero) of the reduction ideal as a :type:`fmpz_mpoly_t`.
+    (indexed from zero) of the reduction ideal as a ``::fmpz_mpoly_t``.
 
 .. macro:: CA_FIELD_IDEAL_LENGTH(K)
 
     Assuming that *K* represents a multivariate field, accesses the number
     of polynomials in the reduction ideal.
 
-.. macro:: CA_FIELD_MCTX(K, ctx)
-
-    Assuming that *K* represents a multivariate field, accesses the
-    :type:`fmpz_mpoly_ctx_t` context object for multivariate polynomial
-    arithmetic on the internal representation of elements in this field.
+.. doxygendefine:: CA_FIELD_MCTX
 
 Memory management
 -------------------------------------------------------------------------------
 
-.. function:: void ca_field_init_qq(ca_field_t K, ca_ctx_t ctx)
-
-    Initializes *K* to represent the trivial field `\mathbb{Q}`.
-
-.. function:: void ca_field_init_nf(ca_field_t K, const qqbar_t x, ca_ctx_t ctx)
-
-    Initializes *K* to represent the algebraic number field `\mathbb{Q}(x)`.
-
-.. function:: void ca_field_init_const(ca_field_t K, calcium_func_code func, ca_ctx_t ctx)
-
-    Initializes *K* to represent the field
-    `\mathbb{Q}(x)` where *x* is a builtin constant defined by
-    *func* (example: *func* = *CA_Pi* for `x = \pi`).
-
-.. function:: void ca_field_init_fx(ca_field_t K, calcium_func_code func, const ca_t x, ca_ctx_t ctx)
-
-    Initializes *K* to represent the field
-    `\mathbb{Q}(a)` where `a = f(x)`, given a number *x* and a builtin
-    univariate function *func* (example: *func* = *CA_Exp* for `e^x`).
-
-.. function:: void ca_field_init_fxy(ca_field_t K, calcium_func_code func, const ca_t x, const ca_t y, ca_ctx_t ctx)
-
-    Initializes *K* to represent the field
-    `\mathbb{Q}(a,b)` where `a = f(x, y)`.
+.. doxygenfunction:: ca_field_init_qq
 
-.. function:: void ca_field_init_multi(ca_field_t K, slong len, ca_ctx_t ctx)
+.. doxygenfunction:: ca_field_init_nf
 
-    Initializes *K* to represent a multivariate field
-    `\mathbb{Q}(a_1, \ldots, a_n)` in *n*
-    extension numbers. The extension numbers must subsequently be
-    assigned one by one using :func:`ca_field_set_ext`.
+.. doxygenfunction:: ca_field_init_const
 
-.. function:: void ca_field_set_ext(ca_field_t K, slong i, ca_ext_srcptr x_index, ca_ctx_t ctx)
+.. doxygenfunction:: ca_field_init_fx
 
-    Sets the extension number at position *i* (here indexed from 0) of *K*
-    to the generator of the field with index *x_index* in *ctx*.
-    (It is assumed that the generating field is a univariate field.)
+.. doxygenfunction:: ca_field_init_fxy
 
-    This only inserts a shallow reference: the field at index *x_index* must
-    be kept alive until *K* has been cleared.
+.. doxygenfunction:: ca_field_init_multi
 
-.. function:: void ca_field_clear(ca_field_t K, ca_ctx_t ctx)
+.. doxygenfunction:: ca_field_set_ext
 
-    Clears the field *K*. This does not clear the individual extension
-    numbers, which are only held as references.
+.. doxygenfunction:: ca_field_clear
 
 Input and output
 -------------------------------------------------------------------------------
 
-.. function:: void ca_field_print(const ca_field_t K, ca_ctx_t ctx)
-
-    Prints a description of the field *K* to standard output.
+.. doxygenfunction:: ca_field_print
 
 Ideal
 -------------------------------------------------------------------------------
 
-.. function:: void ca_field_build_ideal(ca_field_t K, ca_ctx_t ctx)
-
-    Given *K* with assigned extension numbers,
-    builds the reduction ideal in-place.
-
-.. function:: void ca_field_build_ideal_erf(ca_field_t K, ca_ctx_t ctx)
+.. doxygenfunction:: ca_field_build_ideal
 
-    Builds relations for error functions present among the extension
-    numbers in *K*. This heuristic adds relations that are consequences
-    of the functional equations
-    `\operatorname{erf}(x) = -\operatorname{erf}(-x)`,
-    `\operatorname{erfc}(x) = 1-\operatorname{erf}(x)`,
-    `\operatorname{erfi}(x) = -i\operatorname{erf}(ix)`.
+.. doxygenfunction:: ca_field_build_ideal_erf
 
 
 Structure operations
 -------------------------------------------------------------------------------
 
-.. function:: int ca_field_cmp(const ca_field_t K1, const ca_field_t K2, ca_ctx_t ctx)
-
-    Compares the field objects *K1* and *K2* in a canonical sort order,
-    returning -1, 0 or 1. This only performs a lexicographic comparison
-    of the representations of *K1* and *K2*; the return value does not say
-    anything meaningful about the relative structures of *K1* and *K2*
-    as mathematical fields.
+.. doxygenfunction:: ca_field_cmp
 
 Cache
 -------------------------------------------------------------------------------
 
-.. type:: ca_field_cache_struct
-
-.. type:: ca_field_cache_t
-
-    Represents a set of distinct :type:`ca_field_t` instances.
-    This object contains an array of pointers to individual heap-allocated
-    :type:`ca_field_struct` objects as well as a hash table for quick
-    lookup.
-
-.. function:: void ca_field_cache_init(ca_field_cache_t cache, ca_ctx_t ctx)
-
-    Initializes *cache* for use.
-
-.. function:: void ca_field_cache_clear(ca_field_cache_t cache, ca_ctx_t ctx)
-
-    Clears *cache*, freeing the memory allocated internally.
-    This does not clear the individual extension
-    numbers, which are only held as references.
+.. doxygenstruct:: ca_field_cache_struct
 
-.. function:: ca_field_ptr ca_field_cache_insert_ext(ca_field_cache_t cache, ca_ext_struct ** x, slong len, ca_ctx_t ctx)
+.. doxygentypedef:: ca_field_cache_t
 
-    Adds the field defined by the length-*len* list of extension numbers *x*
-    to *cache* without duplication. If such a field already exists in *cache*,
-    a pointer to that instance is returned. Otherwise, a field with
-    extension numbers *x* is inserted into *cache* and a pointer to that
-    new instance is returned. Upon insertion of a new field, the
-    reduction ideal is constructed via :func:`ca_field_build_ideal`.
+.. doxygenfunction:: ca_field_cache_init
 
+.. doxygenfunction:: ca_field_cache_clear
 
+.. doxygenfunction:: ca_field_cache_insert_ext
 
 .. raw:: latex
 
     \newpage
 
+.. doxygenstruct:: ca_field_struct
+    :members:

doc/source/conf.py

@@ -51,6 +51,7 @@
 extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.autodoc',
+    'breathe'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -137,6 +138,12 @@
 #
 # html_sidebars = {}
 
+mathjax3_config = {
+  "tex": {
+    "inlineMath": [['$', '$'], ['\\(', '\\)']]
+  }, }
+
+
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -199,3 +206,8 @@
 
 
 # -- Extension configuration -------------------------------------------------
+breathe_default_project = "my_project"
+breathe_projects_source = {
+    "my_project" : ( "../../src/", ["ca_field.h"] )
+}
+

doc/source/fmpz_mpoly.rst

@@ -21,9 +21,7 @@ Types, macros and constants
 
     Context structure representing the parent ring of an ``fmpz_mpoly``.
 
-.. type:: fmpz_mpoly_ctx_t
-
-    An array of length `1` of ``fmpz_mpoly_ctx_struct``.
+.. doxygentypedef:: fmpz_mpoly_ctx_t
 
 
 Context object

src/ca.h

@@ -8,6 +8,7 @@
     by the Free Software Foundation; either version 2.1 of the License, or
     (at your option) any later version.  See <http://www.gnu.org/licenses/>.
 */
+/** @file */
 
 #ifndef CA_H
 #define CA_H
@@ -153,9 +154,10 @@ typedef ca_ext_cache_struct ca_ext_cache_t[1];
 
 typedef struct
 {
-    slong length;                /* Number of generators              */
-    ca_ext_struct ** ext;        /* Generators                        */
-    fmpz_mpoly_vec_struct ideal; /* Algebraic relations for reduction */
+    slong length;                /**< Number of generators              */
+    ca_ext_struct ** ext;        /**< Generators                        */
+    fmpz_mpoly_vec_struct ideal;
+    /**> Algebraic relations for reduction */
     ulong hash;
 }
 ca_field_struct;
@@ -164,6 +166,7 @@ typedef ca_field_struct ca_field_t[1];
 typedef ca_field_struct * ca_field_ptr;
 typedef const ca_field_struct * ca_field_srcptr;
 
+/** length */
 #define CA_FIELD_LENGTH(K) ((K)->length)
 #define CA_FIELD_EXT(K) ((K)->ext)
 #define CA_FIELD_EXT_ELEM(K, i) ((K)->ext[i])
@@ -183,8 +186,16 @@ typedef const ca_field_struct * ca_field_srcptr;
 #define CA_FIELD_IDEAL_P(K) ((K)->ideal.p)
 
 #define CA_MCTX_1(ctx) ((ctx)->mctx[0])
+/**
+
+    Assuming that *K* represents a multivariate field, accesses the
+    :type:`fmpz_mpoly_ctx_t` context object for multivariate polynomial
+    arithmetic on the internal representation of elements in this field.
+*/
 #define CA_FIELD_MCTX(K, ctx) ((ctx)->mctx[CA_FIELD_LENGTH(K) - 1])
 
+/**
+ */
 typedef struct
 {
     ca_field_struct ** items;
@@ -196,6 +207,14 @@ typedef struct
 }
 ca_field_cache_struct;
 
+
+/**
+ *
+    Represents a set of distinct :type:`ca_field_t` instances.
+    This object contains an array of pointers to individual heap-allocated
+    :type:`ca_field_struct` objects as well as a hash table for quick
+    lookup.
+*/
 typedef ca_field_cache_struct ca_field_cache_t[1];
 
 /* Context object ************************************************************/

src/ca_field/build_ideal.c

@@ -894,6 +894,11 @@ fmpz_mpoly_set_coeff_si_x(fmpz_mpoly_t poly,
         slong x_var, slong x_exp,
         const fmpz_mpoly_ctx_t ctx);
 
+/**
+
+    Given *K* with assigned extension numbers,
+    builds the reduction ideal in-place.
+*/
 void
 ca_field_build_ideal(ca_field_t K, ca_ctx_t ctx)
 {

src/ca_field/build_ideal_erf.c

@@ -280,6 +280,15 @@ erf(x) - i*erfi(-i*x)      = 0
 erfc(x) - i*erfi(i*x) - 1  = 0
 erfc(x) + i*erfi(-i*x) - 1 = 0
 */
+/**
+
+    Builds relations for error functions present among the extension
+    numbers in *K*. This heuristic adds relations that are consequences
+    of the functional equations
+    `\operatorname{erf}(x) = -\operatorname{erf}(-x)`,
+    `\operatorname{erfc}(x) = 1-\operatorname{erf}(x)`,
+    `\operatorname{erfi}(x) = -i\operatorname{erf}(ix)`.
+*/
 void
 ca_field_build_ideal_erf(ca_field_t K, ca_ctx_t ctx)
 {

src/ca_field/cache_clear.c

@@ -11,6 +11,10 @@
 
 #include "ca_field.h"
 
+/**
+    Clears *cache*, freeing the memory allocated internally.
+    This does not clear the individual extension
+    numbers, which are only held as references. */
 void
 ca_field_cache_clear(ca_field_cache_t cache, ca_ctx_t ctx)
 {

src/ca_field/cache_init.c

@@ -13,6 +13,10 @@
 
 #define INITIAL_HASH_SIZE 16
 
+/**
+
+    Initializes *cache* for use.
+*/
 void
 ca_field_cache_init(ca_field_cache_t cache, ca_ctx_t ctx)
 {

src/ca_field/cache_insert.c

@@ -104,6 +104,13 @@ ca_field_init_set_ext(ca_field_t K, ca_ext_struct ** ext, slong len, ca_ctx_t ct
 }
 
 
+/*!
+    Adds the field defined by the length-*len* list of extension numbers *x*
+    to *cache* without duplication. If such a field already exists in *cache*,
+    a pointer to that instance is returned. Otherwise, a field with
+    extension numbers *x* is inserted into *cache* and a pointer to that
+    new instance is returned. Upon insertion of a new field, the
+    reduction ideal is constructed via `::ca_field_build_ideal`. */
 ca_field_ptr ca_field_cache_insert_ext(ca_field_cache_t cache, ca_ext_struct ** x, slong length, ca_ctx_t ctx)
 {
     ulong xhash;

src/ca_field/clear.c

@@ -11,6 +11,11 @@
 
 #include "ca_field.h"
 
+/**
+
+    Clears the field *K*. This does not clear the individual extension
+    numbers, which are only held as references.
+*/
 void
 ca_field_clear(ca_field_t K, ca_ctx_t ctx)
 {

src/ca_field/cmp.c

@@ -196,6 +196,14 @@ ca_field_depth(const ca_field_t K, ca_ctx_t ctx)
 }
 
 /* todo: sort on depth? */
+/**
+
+    Compares the field objects *K1* and *K2* in a canonical sort order,
+    returning -1, 0 or 1. This only performs a lexicographic comparison
+    of the representations of *K1* and *K2*; the return value does not say
+    anything meaningful about the relative structures of *K1* and *K2*
+    as mathematical fields.
+*/
 int
 ca_field_cmp(const ca_field_t K1, const ca_field_t K2, ca_ctx_t ctx)
 {