.

bigfile/_bigfile.c

@@ -17,15 +17,21 @@
  *
  * See COPYING file for full licensing terms.
  * See https://www.nexedi.com/licensing for rationale and options.
+ */
+
+/* Package _bigfile provides Python bindings to virtmem.
+ * See _bigfile.h for package overview. */
+
+/* _bigfile organization
+ *
+ * NOTE on refcounting: who holds who
  *
- * ~~~~~~~~
  *
- * TODO big picture module description
- * - what maps to what, briefly
+ *  vma  ->  fileh  ->  file
+ *   ^         |
+ *   +---------+
+ *   fileh->mmaps (kind of weak)
  *
- *   VMA with a buffer/memoryview interface
- *   BigFileH  with mmap (-> vma) and writeout control
- *   BigFile   base class (to allow implementing BigFile backends in python)
  *
  * NOTE virtmem/bigfile functions release/reacquire GIL (see virt_lock()) -
  * thus functions that use them cannot assume they run mutually exclusive to

bigfile/_bigfile.h

@@ -22,7 +22,16 @@
  * See https://www.nexedi.com/licensing for rationale and options.
  */
 
-// XXX doc
+/* Package _bigfile provides Python bindings to virtmem.
+ *
+ * - `BigFile` is base class that allows implementing BigFile backends in Python.
+ *   Users can inherit from BigFile, implement loadblk/storeblk and this way
+ *   provide access to data managed from Python to virtmem subsystem.
+ * - `BigFileH` represents virtmem file handle for opened BigFile.
+ *   It can be mmap'ed and provides writeout control.
+ * - `VMA` represents mmap'ed part of a BigFileH.
+ *   It provides buffer/memoryview interface for data access.
+ */
 
 #include <Python.h>
 #include <wendelin/bigfile/file.h>
@@ -105,16 +114,6 @@ struct PyBigFile {
 typedef struct PyBigFile PyBigFile;
 
 
-/* NOTE on refcounting: who holds who
- *
- *
- *  vma  ->  fileh  ->  file
- *   ^         |
- *   +---------+
- *   fileh->mmaps (kind of weak)
- */
-
-
 #ifdef  __cplusplus
 }
 #endif