Document options

c/tests/test_trees.c

@@ -7052,7 +7052,7 @@ test_init_take_ownership_no_edge_metadata(void)
     tsk_treeseq_free(&ts);
 
     ret = tsk_treeseq_init(&ts, tables, TSK_TAKE_OWNERSHIP);
-    CU_ASSERT_EQUAL_FATAL(ret, TSK_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA);
+    CU_ASSERT_EQUAL_FATAL(ret, TSK_ERR_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA);
 
     tsk_treeseq_free(&ts);
 }

c/tskit/core.c

@@ -377,7 +377,7 @@ tsk_strerror_internal(int err)
         case TSK_ERR_VARIANT_CANT_DECODE_COPY:
             ret = "Can't decode a copy of a variant";
             break;
-        case TSK_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA:
+        case TSK_ERR_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA:
             ret = "A tree sequence can't take ownership of tables with "
                   "TSK_NO_EDGE_METADATA";
             break;

c/tskit/core.h

@@ -70,33 +70,13 @@ extern "C" {
 #define TSK_DBL_DECIMAL_DIG (DBL_DIG + 3)
 #endif
 
-/* We define a specific NAN value for default mutation time which indicates
- * the time is unknown. We use a specific value so that if mutation time is set to
- * a NAN from a computation we can reject it. This specific value is a non-signalling
- * NAN with the last six fraction bytes set to the ascii of "tskit!"
- */
-#define TSK_UNKNOWN_TIME_HEX 0x7FF874736B697421ULL
-static inline double
-__tsk_nan_f(void)
-{
-    const union {
-        uint64_t i;
-        double f;
-    } nan_union = { .i = TSK_UNKNOWN_TIME_HEX };
-    return nan_union.f;
-}
-#define TSK_UNKNOWN_TIME __tsk_nan_f()
-
-#define TSK_TIME_UNITS_UNKNOWN "unknown"
-#define TSK_TIME_UNITS_UNCALIBRATED "uncalibrated"
-
 /**
 @brief Tskit Object IDs.
 
 @rst
 All objects in tskit are referred to by integer IDs corresponding to the
 row they occupy in the relevant table. The ``tsk_id_t`` type should be used
-when manipulating these ID values. The reserved value ``TSK_NULL`` (-1) defines
+when manipulating these ID values. The reserved value :c:macro:`TSK_NULL` (-1) defines
 missing data.
 @endrst
 */
@@ -166,15 +146,54 @@ to the API or ABI are introduced, i.e., internal refactors of bugfixes.
 #define TSK_VERSION_PATCH   15
 /** @} */
 
-/* Node flags */
+/*
+We define a specific NAN value for default mutation time which indicates
+the time is unknown. We use a specific value so that if mutation time is set to
+a NAN from a computation we can reject it. This specific value is a non-signalling
+NAN with the last six fraction bytes set to the ascii of "tskit!"
+*/
+#define TSK_UNKNOWN_TIME_HEX 0x7FF874736B697421ULL
+static inline double
+__tsk_nan_f(void)
+{
+    const union {
+        uint64_t i;
+        double f;
+    } nan_union = { .i = TSK_UNKNOWN_TIME_HEX };
+    return nan_union.f;
+}
+
+/**
+@defgroup GENERIC_CONSTANTS General options flags used in some functions.
+@{
+*/
+/**
+Used in node flags to indicate that a node is a sample node.
+*/
 #define TSK_NODE_IS_SAMPLE 1u
 
-/* The null ID */
+/** 
+Null value used for cases such as absent id references.
+*/
 #define TSK_NULL ((tsk_id_t) -1)
 
-/* Missing data in an array of genotypes */
+/** 
+Value used for missing data in genotype arrays.
+*/
 #define TSK_MISSING_DATA    (-1)
 
+/**
+Value to indicate that a time is unknown. Note that this value is a non-signalling NAN
+whose representation differs from the NAN generated by computations such as divide by zeros.
+*/
+#define TSK_UNKNOWN_TIME __tsk_nan_f()
+
+/** @} */
+
+#define TSK_TIME_UNITS_UNKNOWN "unknown"
+#define TSK_TIME_UNITS_UNCALIBRATED "uncalibrated"
+
+
 #define TSK_FILE_FORMAT_NAME          "tskit.trees"
 #define TSK_FILE_FORMAT_NAME_LENGTH   11
 #define TSK_FILE_FORMAT_VERSION_MAJOR 12
@@ -186,20 +205,31 @@ to the API or ABI are introduced, i.e., internal refactors of bugfixes.
 */
 
 /* Place the commmon options at the top of the space; this way we can start
- * options for individual functions at the bottom without worrying about
- * clashing with the common options */
+options for individual functions at the bottom without worrying about
+clashing with the common options 
+*/
 
-/** @brief Turn on debugging output. Not supported by all functions. */
+/** Turn on debugging output. Not supported by all functions. */
 #define TSK_DEBUG (1u << 31)
 
-/** @brief Do not initialise the parameter object. */
+/** Do not initialise the parameter object. */
 #define TSK_NO_INIT (1u << 30)
 
-/** @brief Do not run integrity checks before performing an operation. */
+/**
+Do not run integrity checks before performing an operation.
+This performance optimisation should not be used unless the calling code can
+guarantee reference integrity within the table collection. References
+to rows not in the table or bad offsets will result in undefined
+behaviour.
+*/
 #define TSK_NO_CHECK_INTEGRITY (1u << 29)
 
-/** @brief Instead of taking a copy of input data, take ownership of it
- *  and its lifecycle */
+/** 
+Instead of taking a copy of input objects, the function should take ownership
+of them and manage their lifecycle. The caller specifying this flag should no
+longer modify or free the object or objects passed. See individual functions
+using this flag for what object it applies to.
+*/
 #define TSK_TAKE_OWNERSHIP (1u << 28)
 
 /** @} */
@@ -346,7 +376,7 @@ An unsupported type was provided for a column in the file.
 #define TSK_ERR_CANNOT_EXTEND_FROM_SELF                             -806
 #define TSK_ERR_SILENT_MUTATIONS_NOT_SUPPORTED                      -807
 #define TSK_ERR_VARIANT_CANT_DECODE_COPY                            -808
-#define TSK_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA                    -809
+#define TSK_ERR_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA                -809
 
 /* Stats errors */
 #define TSK_ERR_BAD_NUM_WINDOWS                                     -900
@@ -510,18 +540,19 @@ tsk_size_t tsk_search_sorted(const double *array, tsk_size_t size, double value)
 double tsk_round(double x, unsigned int ndigits);
 
 /**
-@brief Check if a number is TSK_UNKNOWN_TIME
+@brief Check if a number is ``TSK_UNKNOWN_TIME``
 
 @rst
 Unknown time values in tskit are represented by a particular NaN value. Since NaN values
 are not equal to each other by definition, a simple comparison like
 ``mutation.time == TSK_UNKNOWN_TIME`` will fail even if the mutation's time is
 TSK_UNKNOWN_TIME. This function compares the underlying bit representation of a double
-value and returns true iff it is equal to the specific NaN value TSK_UNKNOWN_TIME.
+value and returns true iff it is equal to the specific NaN value
+:c:macro:`TSK_UNKNOWN_TIME`.
 @endrst
 
 @param val The number to check
-@return true if the number is TSK_UNKNOWN_TIME else false
+@return true if the number is ``TSK_UNKNOWN_TIME`` else false
 */
 bool tsk_is_unknown_time(double val);
 

c/tskit/genotypes.h

@@ -112,8 +112,8 @@ have their genotypes decoded. A copy of this array will be taken by the variant.
 ``NULL`` sentinel value.
 If specified, the genotypes will be decoded to match the index in this allele array.
 If ``NULL`` then alleles will be automatically determined from the mutations encountered.
-@param options Variant options. Either ``0`` or ``TSK_ISOLATED_NOT_MISSING`` which if
-specified indicates that isolated sample nodes should not be decoded as the "missing"
+@param options Variant options. Either ``0`` or ``TSK_ISOLATED_NOT_MISSING`` which
+if specified indicates that isolated sample nodes should not be decoded as the "missing"
 state but as the ancestral state (or the state of any mutation above them).
 @return Return 0 on success or a negative value on failure.
 */