From f430bdb2823ac7596c4db24f230e37fda0bc55ff Mon Sep 17 00:00:00 2001
From: Anton Khirnov <anton@khirnov.net>
Date: Fri, 10 May 2019 14:57:57 +0200
Subject: transfer: add API documentation

---
 transfer.h | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 52 insertions(+), 2 deletions(-)

diff --git a/transfer.h b/transfer.h
index b2133f4..d5c61a4 100644
--- a/transfer.h
+++ b/transfer.h
@@ -35,27 +35,77 @@ enum GridTransferOperator {
 };
 
 typedef struct RegularGrid2D {
-    size_t size[2];
-    double step[2];
+    /**
+     * Number of points in the domain.
+     */
+    size_t              size[2];
+
+    /**
+     * Size of the step between neighbouring grid points.
+     */
+    double              step[2];
 } RegularGrid2D;
 
 typedef struct GridTransferContext {
+    /**
+     * Private data, not to be accessed by the caller.
+     */
     void *priv;
 
+    /**
+     * Thread pool for parallel execution, must be set by the caller.
+     */
     TPContext *tp;
+    /**
+     * CPU feature flags, must be set by the caller.
+     */
     int cpuflags;
 
+    /**
+     * The operator used, set by mg2di_gt_alloc().
+     */
     enum GridTransferOperator op;
 
+    /**
+     * Source grid geometry, must be filled by the caller.
+     */
     RegularGrid2D src;
+
+    /**
+     * Destination grid geometry, must be filled by the caller.
+     */
     RegularGrid2D dst;
 } GridTransferContext;
 
+/**
+ * Allocate the transfer context for the given transfer operator.
+ *
+ * @return newly allocated transfer context on success, NULL on failure
+ */
 GridTransferContext *mg2di_gt_alloc(enum GridTransferOperator op);
+
+/**
+ * Initialize the tranfer context after all the parameters have been set.
+ *
+ * @return 0 on success, a negative error code on failure
+ */
 int mg2di_gt_init(GridTransferContext *ctx);
 
+/**
+ * Free the transfer context and everything associated with it.
+ * Write NULL in the supplied pointer.
+ */
 void mg2di_gt_free(GridTransferContext **ctx);
 
+/**
+ * Execute the transfer.
+ *
+ * @param ctx transfer context
+ * @param dst destination data, must match the dst grid in the transfer context
+ * @param src source data, must match the src grid in the transfer context
+ *
+ * @return 0 on success, a negative error code on failure.
+ */
 int mg2di_gt_transfer(GridTransferContext *ctx,
                       NDArray *dst, const NDArray *src);
 
-- 
cgit v1.2.3