Review: Remove long_u: memfile: Cleanup: Comments.

- Restyle comments (/// when appropiate, // otherwise).
- Improve comments (add new comments, augment/clarify existing ones).

src/nvim/memfile.h

@@ -4,11 +4,11 @@
 #include "nvim/buffer_defs.h"
 #include "nvim/memfile_defs.h"
 
-/* flags for mf_sync() */
+/// flags for mf_sync()
-#define MFS_ALL         1       /* also sync blocks with negative numbers */
+#define MFS_ALL         1       /// also sync blocks with negative numbers
-#define MFS_STOP        2       /* stop syncing when a character is available */
+#define MFS_STOP        2       /// stop syncing when a character is available
-#define MFS_FLUSH       4       /* flushed file to disk */
+#define MFS_FLUSH       4       /// flushed file to disk
-#define MFS_ZERO        8       /* only write block 0 */
+#define MFS_ZERO        8       /// only write block 0
 
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "memfile.h.generated.h"

src/nvim/memfile_defs.h

@@ -4,15 +4,21 @@
 #include "nvim/types.h"
 
 typedef struct block_hdr bhdr_T;
+
+/// A block number.
+///
+/// Blocks numbered from 0 upwards have been assigned a place in the actual
+/// file. The block number is equal to the page number in the file. The blocks
+/// with negative numbers are currently in memory only.
 typedef long blocknr_T;
 
-/*
+/// A hash item.
- * mf_hashtab_T is a chained hashtable with blocknr_T key and arbitrary
+///
- * structures as items.  This is an intrusive data structure: we require
+/// Items' keys are block numbers.
- * that items begin with mf_hashitem_T which contains the key and linked
+/// Items in the same bucket are organized into a doubly-linked list.
- * list pointers.  List of items in each bucket is doubly-linked.
+///
- */
+/// Therefore, items can be arbitrary data structures beginning with pointers
-
+/// for the list and and a block number key.
 typedef struct mf_hashitem_S mf_hashitem_T;
 
 struct mf_hashitem_S {
@@ -21,79 +27,86 @@ struct mf_hashitem_S {
   blocknr_T mhi_key;
 };
 
+/// Initial size for a hashtable.
 #define MHT_INIT_SIZE   64
 
+/// A chained hashtable with block numbers as keys and arbitrary data structures
+/// as items.
+///
+/// This is an intrusive data structure: we require that items begin with
+/// mf_hashitem_T which contains the key and linked list pointers. List of items
+/// in each bucket is doubly-linked.
 typedef struct mf_hashtab_S {
-  long_u mht_mask;                  /* mask used for hash value (nr of items
+  long_u mht_mask;              /// mask used to mod hash value to array index
-                                     * in array is "mht_mask" + 1) */
+                                /// (nr of items in array is 'mht_mask + 1')
-  long_u mht_count;                 /* nr of items inserted into hashtable */
+  long_u mht_count;             /// number of items inserted
-  mf_hashitem_T   **mht_buckets;    /* points to mht_small_buckets or
+  mf_hashitem_T **mht_buckets;  /// points to the array of buckets (can be
-                                     *dynamically allocated array */
+                                /// mht_small_buckets or a newly allocated array
-  mf_hashitem_T   *mht_small_buckets[MHT_INIT_SIZE];     /* initial buckets */
+                                /// when mht_small_buckets becomes too small)
-  char mht_fixed;                   /* non-zero value forbids growth */
+  mf_hashitem_T *mht_small_buckets[MHT_INIT_SIZE];     /// initial buckets
+  char mht_fixed;               /// non-zero value forbids growth
 } mf_hashtab_T;
 
-/*
+/// A block header.
- * for each (previously) used block in the memfile there is one block header.
+///
- *
+/// There is a block header for each previously used block in the memfile.
- * The block may be linked in the used list OR in the free list.
+///
- * The used blocks are also kept in hash lists.
+/// The block may be linked in the used list OR in the free list.
- *
+/// The used blocks are also kept in hash lists.
- * The used list is a doubly linked list, most recently used block first.
+///
- *	The blocks in the used list have a block of memory allocated.
+/// The used list is a doubly linked list, most recently used block first.
- *	mf_used_count is the number of pages in the used list.
+/// The blocks in the used list have a block of memory allocated.
- * The hash lists are used to quickly find a block in the used list.
+/// mf_used_count is the number of pages in the used list.
- * The free list is a single linked list, not sorted.
+/// The hash lists are used to quickly find a block in the used list.
- *	The blocks in the free list have no block of memory allocated and
+/// The free list is a single linked list, not sorted.
- *	the contents of the block in the file (if any) is irrelevant.
+/// The blocks in the free list have no block of memory allocated and
- */
+/// the contents of the block in the file (if any) is irrelevant.
-
 struct block_hdr {
-  mf_hashitem_T bh_hashitem;        /* header for hash table and key */
+  mf_hashitem_T bh_hashitem;         /// header for hash table and key
-#define bh_bnum bh_hashitem.mhi_key /* block number, part of bh_hashitem */
+#define bh_bnum bh_hashitem.mhi_key  /// block number, part of bh_hashitem
 
-  bhdr_T      *bh_next;             /* next block_hdr in free or used list */
+  bhdr_T *bh_next;                   /// next block_hdr in free or used list
-  bhdr_T      *bh_prev;             /* previous block_hdr in used list */
+  bhdr_T *bh_prev;                   /// previous block_hdr in used list
-  char_u      *bh_data;             /* pointer to memory (for used block) */
+  char_u *bh_data;                   /// pointer to memory (for used block)
-  int bh_page_count;                /* number of pages in this block */
+  int bh_page_count;                 /// number of pages in this block
 
 #define BH_DIRTY    1
 #define BH_LOCKED   2
-  char bh_flags;                    /* BH_DIRTY or BH_LOCKED */
+  char bh_flags;                     // BH_DIRTY or BH_LOCKED
 };
 
-/*
+/// A block number translation list item.
- * when a block with a negative number is flushed to the file, it gets
+///
- * a positive number. Because the reference to the block is still the negative
+/// When a block with a negative number is flushed to the file, it gets
- * number, we remember the translation to the new positive number in the
+/// a positive number. Because the reference to the block is still the negative
- * double linked trans lists. The structure is the same as the hash lists.
+/// number, we remember the translation to the new positive number in the
- */
+/// double linked trans lists. The structure is the same as the hash lists.
 typedef struct nr_trans NR_TRANS;
 
 struct nr_trans {
-  mf_hashitem_T nt_hashitem;            /* header for hash table and key */
+  mf_hashitem_T nt_hashitem;             /// header for hash table and key
-#define nt_old_bnum nt_hashitem.mhi_key /* old, negative, number */
+#define nt_old_bnum nt_hashitem.mhi_key  /// old, negative, number
-
+  blocknr_T nt_new_bnum;                 /// new, positive, number
-  blocknr_T nt_new_bnum;                /* new, positive, number */
 };
 
+/// A memory file.
 struct memfile {
-  char_u      *mf_fname;                /* name of the file */
+  char_u *mf_fname;                  /// name of the file
-  char_u      *mf_ffname;               /* idem, full path */
+  char_u *mf_ffname;                 /// idem, full path
-  int mf_fd;                            /* file descriptor */
+  int mf_fd;                         /// file descriptor
-  bhdr_T      *mf_free_first;           /* first block_hdr in free list */
+  bhdr_T *mf_free_first;             /// first block_hdr in free list
-  bhdr_T      *mf_used_first;           /* mru block_hdr in used list */
+  bhdr_T *mf_used_first;             /// mru block_hdr in used list
-  bhdr_T      *mf_used_last;            /* lru block_hdr in used list */
+  bhdr_T *mf_used_last;              /// lru block_hdr in used list
-  unsigned mf_used_count;               /* number of pages in used list */
+  unsigned mf_used_count;            /// number of pages in used list
-  unsigned mf_used_count_max;           /* maximum number of pages in memory */
+  unsigned mf_used_count_max;        /// maximum number of pages in memory
-  mf_hashtab_T mf_hash;                 /* hash lists */
+  mf_hashtab_T mf_hash;              /// hash lists
-  mf_hashtab_T mf_trans;                /* trans lists */
+  mf_hashtab_T mf_trans;             /// trans lists
-  blocknr_T mf_blocknr_max;             /* highest positive block number + 1*/
+  blocknr_T mf_blocknr_max;          /// highest positive block number + 1
-  blocknr_T mf_blocknr_min;             /* lowest negative block number - 1 */
+  blocknr_T mf_blocknr_min;          /// lowest negative block number - 1
-  blocknr_T mf_neg_count;               /* number of negative blocks numbers */
+  blocknr_T mf_neg_count;            /// number of negative blocks numbers
-  blocknr_T mf_infile_count;            /* number of pages in the file */
+  blocknr_T mf_infile_count;         /// number of pages in the file
-  unsigned mf_page_size;                /* number of bytes in a page */
+  unsigned mf_page_size;             /// number of bytes in a page
-  int mf_dirty;                         /* TRUE if there are dirty blocks */
+  int mf_dirty;                      /// TRUE if there are dirty blocks
 };
 
 #endif // NVIM_MEMFILE_DEFS_H