Initial outline of C API docs

Author: jeromekelleher

.circleci/config.yml

@@ -100,7 +100,7 @@ jobs:
       #       ./build-clang/malloc_tests
       #       ./build-clang/io_tests
 
-      # - run:
-      #     name: Build docs
-      #     command: |
-      #       cd docs && make
+      - run:
+          name: Build docs
+          command: |
+            cd docs && make

c/tsk_core.h

@@ -1,3 +1,7 @@
+/**
+ * @file tsk_core.h
+ * @brief Core utilities used in all of tskit.
+ */
 #ifndef __TSK_CORE_H__
 #define __TSK_CORE_H__
 
@@ -53,7 +57,6 @@
      TSK_CHECK_SITE_DUPLICATES | TSK_CHECK_MUTATION_ORDERING | TSK_CHECK_INDEXES)
 
 /* Flags for dump tables */
-/* #define TSK_ALLOC_TABLES 1 */
 
 /* Flags for load tables */
 #define TSK_BUILD_INDEXES 1
@@ -69,21 +72,51 @@
 #define TSK_FILE_FORMAT_VERSION_MAJOR 12
 #define TSK_FILE_FORMAT_VERSION_MINOR 0
 
-/* Error codes */
+/**
+@defgroup GENERAL_ERROR_GROUP General errors.
+@{
+*/
 
-/* General errrors */
+/**
+Generic error thrown when no other message can be generated.
+*/
 #define TSK_ERR_GENERIC                                             -1
+/**
+Memory could not be allocated.
+*/
 #define TSK_ERR_NO_MEMORY                                           -2
+/**
+An IO error occured.
+*/
 #define TSK_ERR_IO                                                  -3
 #define TSK_ERR_BAD_PARAM_VALUE                                     -4
 #define TSK_ERR_BUFFER_OVERFLOW                                     -5
 #define TSK_ERR_UNSUPPORTED_OPERATION                               -6
 #define TSK_ERR_GENERATE_UUID                                       -7
+/** @} */
+
+/**
+@defgroup FILE_FORMAT_ERROR_GROUP File format errors.
+@{
+*/
 
-/* File format errors */
+/**
+A file could not be read because it is in the wrong format
+*/
 #define TSK_ERR_FILE_FORMAT                                         -100
+/**
+The file is in tskit format, but the version is too old for the
+library to read. The file should be upgraded to the latest version
+using the ``tskit upgrade`` command line utility.
+*/
 #define TSK_ERR_FILE_VERSION_TOO_OLD                                -101
+/**
+The file is in tskit format, but the version is too new for the
+library to read. To read the file you must upgrade the version
+of tskit.
+*/
 #define TSK_ERR_FILE_VERSION_TOO_NEW                                -102
+/** @} */
 
 /* Out of bounds errors */
 #define TSK_ERR_BAD_OFFSET                                          -200
@@ -139,6 +172,7 @@
 #define TSK_ERR_SIMPLIFY_MIGRATIONS_NOT_SUPPORTED                   -801
 #define TSK_ERR_NONBINARY_MUTATIONS_UNSUPPORTED                     -802
 
+
 /* This bit is 0 for any errors originating from kastore */
 #define TSK_KAS_ERR_BIT 14
 

c/tsk_tables.h

@@ -1,3 +1,7 @@
+/**
+ * @file tsk_tables.h
+ * @brief Tskit Tables API.
+ */
 #ifndef TSK_TABLES_H
 #define TSK_TABLES_H
 
@@ -99,6 +103,9 @@ typedef struct {
 /* Table definitions */
 /****************************************************************************/
 
+/**
+@brief The individual table.
+*/
 typedef struct {
     tsk_tbl_size_t num_rows;
     tsk_tbl_size_t max_rows;
@@ -116,6 +123,9 @@ typedef struct {
     tsk_tbl_size_t *metadata_offset;
 } tsk_individual_tbl_t;
 
+/**
+@brief The node table.
+*/
 typedef struct {
     tsk_tbl_size_t num_rows;
     tsk_tbl_size_t max_rows;
@@ -131,6 +141,9 @@ typedef struct {
     tsk_tbl_size_t *metadata_offset;
 } tsk_node_tbl_t;
 
+/**
+@brief The site table.
+*/
 typedef struct {
     tsk_tbl_size_t num_rows;
     tsk_tbl_size_t max_rows;
@@ -148,6 +161,9 @@ typedef struct {
     tsk_tbl_size_t *metadata_offset;
 } tsk_site_tbl_t;
 
+/**
+@brief The mutation table.
+*/
 typedef struct {
     tsk_tbl_size_t num_rows;
     tsk_tbl_size_t max_rows;
@@ -167,6 +183,9 @@ typedef struct {
     tsk_tbl_size_t *metadata_offset;
 } tsk_mutation_tbl_t;
 
+/**
+@brief The edge table.
+*/
 typedef struct {
     tsk_tbl_size_t num_rows;
     tsk_tbl_size_t max_rows;
@@ -177,6 +196,9 @@ typedef struct {
     tsk_id_t *child;
 } tsk_edge_tbl_t;
 
+/**
+@brief The migration table.
+*/
 typedef struct {
     tsk_tbl_size_t num_rows;
     tsk_tbl_size_t max_rows;
@@ -189,6 +211,9 @@ typedef struct {
     double *time;
 } tsk_migration_tbl_t;
 
+/**
+@brief The population table.
+*/
 typedef struct {
     tsk_tbl_size_t num_rows;
     tsk_tbl_size_t max_rows;
@@ -200,6 +225,9 @@ typedef struct {
     tsk_tbl_size_t *metadata_offset;
 } tsk_population_tbl_t;
 
+/**
+@brief The provenance table.
+*/
 typedef struct {
     tsk_tbl_size_t num_rows;
     tsk_tbl_size_t max_rows;
@@ -216,10 +244,16 @@ typedef struct {
     tsk_tbl_size_t *record_offset;
 } tsk_provenance_tbl_t;
 
+/**
+@brief The table collection.
+*/
 typedef struct {
+    /** @brief The sequence length defining the tree sequence's coordinate space */
     double sequence_length;
     char *file_uuid;
+    /** @brief The individual table */
     tsk_individual_tbl_t *individuals;
+    /* TODO document other public members */
     tsk_node_tbl_t *nodes;
     tsk_edge_tbl_t *edges;
     tsk_migration_tbl_t *migrations;
@@ -438,7 +472,32 @@ int tsk_provenance_tbl_get_row(tsk_provenance_tbl_t *self, size_t index, tsk_pro
 /* Table collection .*/
 /****************************************************************************/
 
+/**
+@brief Allocate a new table collection.
+
+@rst
+After allocation, each of the consituent tables is allocated with the default size increment.
+The sequence length is set to zero.
+@endrst
+
+@param self A pointer to an uninitialised tsk_tbl_collection_t object.
+@param flags Allocation time options. Currently unused.
+@return Return 0 on success or a negative value on failure.
+*/
 int tsk_tbl_collection_alloc(tsk_tbl_collection_t *self, int flags);
+
+/**
+@brief Load a table collection from file.
+
+@rst
+Reads a table collection from the specified file.
+@endrst
+
+@param self A pointer to an uninitialised tsk_tbl_collection_t object.
+@param filename A NULL terminated string containing the filename.
+@param flags Load time options. Currently unused.
+@return Return 0 on success or a negative value on failure.
+*/
 int tsk_tbl_collection_load(tsk_tbl_collection_t *self, const char *filename, int flags);
 int tsk_tbl_collection_dump(tsk_tbl_collection_t *tables, const char *filename, int flags);
 int tsk_tbl_collection_copy(tsk_tbl_collection_t *self, tsk_tbl_collection_t *dest);

c/tsk_trees.h

@@ -1,3 +1,7 @@
+/**
+ * @file tsk_trees.h
+ * @brief Tskit core tree sequence operations.
+ */
 #ifndef TSK_TREES_H
 #define TSK_TREES_H
 
@@ -15,7 +19,9 @@ extern "C" {
 #define TSK_DIR_REVERSE -1
 
 
-/* Tree sequences */
+/**
+@brief The tree sequence object.
+*/
 typedef struct {
     size_t num_trees;
     size_t num_samples;
@@ -104,8 +110,35 @@ typedef struct {
 /* Tree sequence.*/
 /****************************************************************************/
 
+/**
+@brief Allocate a new tree sequence from a table collection.
+
+@rst
+A tree sequence is a read-only view of a table collection with extra
+structures that facilitate efficient tree iteratation and other operations.
+@endrst
+
+@param self A pointer to an uninitialised tsk_treeseq_t object.
+@param tables A pointer to a tsk_tbl_collection_t object.
+@param flags Allocation time options.
+@return Return 0 on success or a negative value on failure.
+*/
 int tsk_treeseq_alloc(tsk_treeseq_t *self, tsk_tbl_collection_t *tables, int flags);
+
+/**
+@brief Load a tree sequence from file.
+
+@rst
+Reads a tree sequence from the specified file.
+@endrst
+
+@param self A pointer to an uninitialised tsk_treeseq_t object.
+@param filename A NULL terminated string containing the filename.
+@param flags Load time options. Currently unused.
+@return Return 0 on success or a negative value on failure.
+*/
 int tsk_treeseq_load(tsk_treeseq_t *self, const char *filename, int flags);
+
 int tsk_treeseq_dump(tsk_treeseq_t *self, const char *filename, int flags);
 int tsk_treeseq_copy_tables(tsk_treeseq_t *self, tsk_tbl_collection_t *tables);
 int tsk_treeseq_free(tsk_treeseq_t *self);

c/tskit.h

@@ -1,3 +1,7 @@
+/**
+ * @file tskit.h
+ * @brief Tskit API.
+ */
 #ifndef __TSKIT_H__
 #define __TSKIT_H__
 

docs/Makefile

@@ -9,10 +9,10 @@ BUILDDIR      = _build
 
 DOXYGEN_XML=doxygen/xml
 
-all: #${DOXYGEN_XML}
+all: ${DOXYGEN_XML}
 	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-${DOXYGEN_XML}: ../c/kastore.h
+${DOXYGEN_XML}: ../c/tskit.h
 	cd doxygen && doxygen
 
 # Put it first so that "make" without argument is like "make help".

docs/c-api.rst

@@ -4,3 +4,51 @@
 C API
 =====
 
+.. warning::
+        **This section is under construction, incomplete and experiemental!!**
+
+**********
+Tables API
+**********
+
+.. doxygenstruct:: tsk_tbl_collection_t
+    :members:
+
+.. doxygenfunction:: tsk_tbl_collection_alloc
+
+.. doxygenfunction:: tsk_tbl_collection_load
+
+**************
+Tree sequences
+**************
+
+.. doxygenstruct:: tsk_treeseq_t
+    :members:
+
+.. doxygenfunction:: tsk_treeseq_alloc
+
+.. doxygenfunction:: tsk_treeseq_load
+
+
+*********
+Constants
+*********
+
+.. _sec_c_api_error_codes:
+
+--------------
+Generic Errors
+--------------
+
+.. doxygengroup:: GENERAL_ERROR_GROUP
+        :content-only:
+
+------------------
+File format errors
+------------------
+
+.. doxygengroup:: FILE_FORMAT_ERROR_GROUP
+        :content-only:
+
+
+.. todo:: Add in groups for rest of the error types and document.

docs/conf.py

@@ -15,6 +15,24 @@
 import subprocess
 import os
 import sys
+
+# It's easier not to try to build the low-level module for the
+# documentation build on readthedocs, so we mock the module. Follows
+# the recommended pattern at
+# http://docs.readthedocs.org/en/latest/faq.html
+
+from unittest.mock import MagicMock
+
+
+class Mock(MagicMock):
+    @classmethod
+    def __getattr__(cls, name):
+        return MagicMock()
+
+MOCK_MODULES = ["_tskit"]
+sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
+
+
 sys.path.insert(0, os.path.abspath('../python'))
 
 read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'