Review: Remove long_u: memfile: Cleanup: Comments.

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

3 files changed, 433 insertions, 519 deletions

diff --git a/src/nvim/memfile.c b/src/nvim/memfile.c
index 827cff2299..ca6628afb1 100644
--- a/src/nvim/memfile.c
+++ b/src/nvim/memfile.c
@@ -1,35 +1,47 @@
 /*
- * VIM - Vi IMproved	by Bram Moolenaar
+ * VIM - Vi IMproved    by Bram Moolenaar
  *
  * Do ":help uganda"  in Vim to read copying and usage conditions.
  * Do ":help credits" in Vim to see a list of people who contributed.
  * See README.txt for an overview of the Vim source code.
  */
 
-/*
- * memfile.c: Contains the functions for handling blocks of memory which can
- * be stored in a file. This is the implementation of a sort of virtual memory.
- *
- * A memfile consists of a sequence of blocks. The 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. They can be
- * assigned a place in the file when too much memory is being used. At that
- * moment they get a new, positive, number. A list is used for translation of
- * negative to positive numbers.
- *
- * The size of a block is a multiple of a page size, normally the page size of
- * the device the file is on. Most blocks are 1 page long. A Block of multiple
- * pages is used for a line that does not fit in a single page.
- *
- * Each block can be in memory and/or in a file. The block stays in memory
- * as long as it is locked. If it is no longer locked it can be swapped out to
- * the file. It is only written to the file if it has been changed.
- *
- * Under normal operation the file is created when opening the memory file and
- * deleted when closing the memory file. Only with recovery an existing memory
- * file is opened.
- */
+/// An abstraction to handle blocks of memory which can be stored in a file.
+/// This is the implementation of a sort of virtual memory.
+///
+/// A memfile consists of a sequence of blocks:
+/// - 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.
+/// - Blocks with negative numbers are currently in memory only. They can be
+///   assigned a place in the file when too much memory is being used. At that
+///   moment, they get a new, positive, number. A list is used for translation
+///   of negative to positive numbers.
+///
+/// The size of a block is a multiple of a page size, normally the page size of
+/// the device the file is on. Most blocks are 1 page long. A block of multiple
+/// pages is used for a line that does not fit in a single page.
+///
+/// Each block can be in memory and/or in a file. The block stays in memory
+/// as long as it is locked. If it is no longer locked it can be swapped out to
+/// the file. It is only written to the file if it has been changed.
+///
+/// Under normal operation the file is created when opening the memory file and
+/// deleted when closing the memory file. Only with recovery an existing memory
+/// file is opened.
+///
+/// The functions for using a memfile:
+///
+/// mf_open()         open a new or existing memfile
+/// mf_open_file()    open a swap file for an existing memfile
+/// mf_close()        close (and delete) a memfile
+/// mf_new()          create a new block in a memfile and lock it
+/// mf_get()          get an existing block and lock it
+/// mf_put()          unlock a block, may be marked for writing
+/// mf_free()         remove a block
+/// mf_sync()         sync changed parts of memfile to disk
+/// mf_release_all()  release as much memory as possible
+/// mf_trans_del()    may translate negative to positive block number
+/// mf_fullname()     make file name full path (use before first :cd)
 
 #include <errno.h>
 #include <inttypes.h>
@@ -49,64 +61,49 @@
 #include "nvim/ui.h"
 #include "nvim/os/os.h"
 
-#define MEMFILE_PAGE_SIZE 4096          /* default page size */
+#define MEMFILE_PAGE_SIZE 4096       /// default page size
 
-static long_u total_mem_used = 0;       /* total memory used for memfiles */
 
+static long_u total_mem_used = 0;    /// total memory used for memfiles
 
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "memfile.c.generated.h"
 #endif
-/*
- * The functions for using a memfile:
- *
- * mf_open()	    open a new or existing memfile
- * mf_open_file()   open a swap file for an existing memfile
- * mf_close()	    close (and delete) a memfile
- * mf_new()	    create a new block in a memfile and lock it
- * mf_get()	    get an existing block and lock it
- * mf_put()	    unlock a block, may be marked for writing
- * mf_free()	    remove a block
- * mf_sync()	    sync changed parts of memfile to disk
- * mf_release_all() release as much memory as possible
- * mf_trans_del()   may translate negative to positive block number
- * mf_fullname()    make file name full path (use before first :cd)
- */
 
-/*
- * Open an existing or new memory block file.
- *
- *  fname:	name of file to use (NULL means no file at all)
- *		Note: fname must have been allocated, it is not copied!
- *			If opening the file fails, fname is freed.
- *  flags:	flags for open() call
- *
- *  If fname != NULL and file cannot be opened, fail.
- *
- * return value: identifier for this memory block file.
- */
+/// Open a new or existing memory block file.
+///
+/// @param fname  Name of file to use.
+///               - If NULL, it means no file (use memory only).
+///               - If not NULL:
+///                 * Should correspond to an existing file.
+///                 * String must have been allocated (it is not copied).
+///                 * If opening the file fails, it is freed and function fails.
+
+/// @param flags  Flags for open() call.
+///
+/// @return - The open memory file, on success.
+///         - NULL, on failure.
 memfile_T *mf_open(char_u *fname, int flags)
 {
   off_t size;
 
   memfile_T *mfp = xmalloc(sizeof(memfile_T));
 
-  if (fname == NULL) {      /* no file for this memfile, use memory only */
+  if (fname == NULL) {               // no file, use memory only
     mfp->mf_fname = NULL;
     mfp->mf_ffname = NULL;
     mfp->mf_fd = -1;
-  } else {
-    mf_do_open(mfp, fname, flags);      /* try to open the file */
+  } else {                           // try to open the file
+    mf_do_open(mfp, fname, flags);
 
-    /* if the file cannot be opened, return here */
-    if (mfp->mf_fd < 0) {
+    if (mfp->mf_fd < 0) {            // fail if file could not be opened
       free(mfp);
       return NULL;
     }
   }
 
-  mfp->mf_free_first = NULL;            /* free list is empty */
-  mfp->mf_used_first = NULL;            /* used list is empty */
+  mfp->mf_free_first = NULL;         // free list is empty
+  mfp->mf_used_first = NULL;         // used list is empty
   mfp->mf_used_last = NULL;
   mfp->mf_dirty = FALSE;
   mfp->mf_used_count = 0;
@@ -114,13 +111,7 @@ memfile_T *mf_open(char_u *fname, int flags)
   mf_hash_init(&mfp->mf_trans);
   mfp->mf_page_size = MEMFILE_PAGE_SIZE;
 
-  /*
-   * Try to set the page size equal to the block size of the device.
-   * Speeds up I/O a lot.
-   * When recovering, the actual block size will be retrieved from block 0
-   * in ml_recover().  The size used here may be wrong, therefore
-   * mf_blocknr_max must be rounded up.
-   */
+  // Try to set the page size equal to device's block size. Speeds up I/O a lot.
   FileInfo file_info;
   if (mfp->mf_fd >= 0 && os_fileinfo_fd(mfp->mf_fd, &file_info)) {
     uint64_t blocksize = os_fileinfo_blocksize(&file_info);
@@ -129,9 +120,13 @@ memfile_T *mf_open(char_u *fname, int flags)
     }
   }
 
+  // When recovering, the actual block size will be retrieved from block 0
+  // in ml_recover(). The size used here may be wrong, therefore mf_blocknr_max
+  // must be rounded up.
   if (mfp->mf_fd < 0 || (flags & (O_TRUNC|O_EXCL))
       || (size = lseek(mfp->mf_fd, (off_t)0L, SEEK_END)) <= 0)
-    mfp->mf_blocknr_max = 0;            /* no file or empty file */
+    // no file or empty file
+    mfp->mf_blocknr_max = 0;
   else
     mfp->mf_blocknr_max = (blocknr_T)((size + mfp->mf_page_size - 1)
                                       / mfp->mf_page_size);
@@ -139,11 +134,9 @@ memfile_T *mf_open(char_u *fname, int flags)
   mfp->mf_neg_count = 0;
   mfp->mf_infile_count = mfp->mf_blocknr_max;
 
-  /*
-   * Compute maximum number of pages ('maxmem' is in Kbyte):
-   *	'mammem' * 1Kbyte / page-size-in-bytes.
-   * Avoid overflow by first reducing page size as much as possible.
-   */
+  // Compute maximum number of pages ('maxmem' is in Kbytes):
+  //	'mammem' * 1Kbyte / page-size-in-bytes.
+  // Avoid overflow by first reducing page size as much as possible.
   {
     int shift = 10;
     unsigned page_size = mfp->mf_page_size;
@@ -152,6 +145,7 @@ memfile_T *mf_open(char_u *fname, int flags)
       page_size /= 2;
       --shift;
     }
+
     mfp->mf_used_count_max = (p_mm << shift) / page_size;
     if (mfp->mf_used_count_max < 10)
       mfp->mf_used_count_max = 10;
@@ -160,19 +154,22 @@ memfile_T *mf_open(char_u *fname, int flags)
   return mfp;
 }
 
-/*
- * Open a file for an existing memfile.  Used when updatecount set from 0 to
- * some value.
- * If the file already exists, this fails.
- * "fname" is the name of file to use (NULL means no file at all)
- * Note: "fname" must have been allocated, it is not copied!  If opening the
- * file fails, "fname" is freed.
- *
- * return value: FAIL if file could not be opened, OK otherwise
- */
+/// Open a file for an existing memfile.
+///
+/// Used when updatecount set from 0 to some value.
+///
+/// @param fname  Name of file to use.
+///               - If NULL, it means no file (use memory only).
+///               - If not NULL:
+///                 * Should correspond to an existing file.
+///                 * String must have been allocated (it is not copied).
+///                 * If opening the file fails, it is freed and function fails.
+///
+/// @return OK    On success.
+///         FAIL  If file could not be opened.
 int mf_open_file(memfile_T *mfp, char_u *fname)
 {
-  mf_do_open(mfp, fname, O_RDWR|O_CREAT|O_EXCL);   /* try to open the file */
+  mf_do_open(mfp, fname, O_RDWR|O_CREAT|O_EXCL);  // try to open the file
 
   if (mfp->mf_fd < 0)
     return FAIL;
@@ -181,14 +178,14 @@ int mf_open_file(memfile_T *mfp, char_u *fname)
   return OK;
 }
 
-/*
- * Close a memory file and delete the associated file if 'del_file' is TRUE.
- */
+/// Close a memory file and optionally delete the associated file.
+///
+/// @param del_file  TRUE to delete associated file.
 void mf_close(memfile_T *mfp, int del_file)
 {
   bhdr_T      *hp, *nextp;
 
-  if (mfp == NULL)                  /* safety check */
+  if (mfp == NULL)                      // safety check
     return;
   if (mfp->mf_fd >= 0) {
     if (close(mfp->mf_fd) < 0)
@@ -196,52 +193,48 @@ void mf_close(memfile_T *mfp, int del_file)
   }
   if (del_file && mfp->mf_fname != NULL)
     os_remove((char *)mfp->mf_fname);
-  /* free entries in used list */
+  // free entries in used list
   for (hp = mfp->mf_used_first; hp != NULL; hp = nextp) {
     total_mem_used -= hp->bh_page_count * mfp->mf_page_size;
     nextp = hp->bh_next;
     mf_free_bhdr(hp);
   }
-  while (mfp->mf_free_first != NULL)        /* free entries in free list */
+  while (mfp->mf_free_first != NULL)    // free entries in free list
     free(mf_rem_free(mfp));
   mf_hash_free(&mfp->mf_hash);
-  mf_hash_free_all(&mfp->mf_trans);         /* free hashtable and its items */
+  mf_hash_free_all(&mfp->mf_trans);     // free hashtable and its items
   free(mfp->mf_fname);
   free(mfp->mf_ffname);
   free(mfp);
 }
 
-/*
- * Close the swap file for a memfile.  Used when 'swapfile' is reset.
- */
-void 
-mf_close_file (
-    buf_T *buf,
-    int getlines                   /* get all lines into memory? */
-)
+/// Close the swap file for a memfile. Used when 'swapfile' is reset.
+///
+/// @param getlines  TRUE to get all lines into memory.
+void mf_close_file (buf_T *buf, int getlines)
 {
   memfile_T   *mfp;
   linenr_T lnum;
 
   mfp = buf->b_ml.ml_mfp;
-  if (mfp == NULL || mfp->mf_fd < 0)            /* nothing to close */
+  if (mfp == NULL || mfp->mf_fd < 0)     // nothing to close
     return;
 
   if (getlines) {
-    /* get all blocks in memory by accessing all lines (clumsy!) */
+    // get all blocks in memory by accessing all lines (clumsy!)
     mf_dont_release = TRUE;
     for (lnum = 1; lnum <= buf->b_ml.ml_line_count; ++lnum)
       (void)ml_get_buf(buf, lnum, FALSE);
     mf_dont_release = FALSE;
-    /* TODO: should check if all blocks are really in core */
+    // TODO: should check if all blocks are really in core
   }
 
-  if (close(mfp->mf_fd) < 0)                    /* close the file */
+  if (close(mfp->mf_fd) < 0)             // close the file
     EMSG(_(e_swapclose));
   mfp->mf_fd = -1;
 
   if (mfp->mf_fname != NULL) {
-    os_remove((char *)mfp->mf_fname);  // delete the swap file
+    os_remove((char *)mfp->mf_fname);    // delete the swap file
     free(mfp->mf_fname);
     free(mfp->mf_ffname);
     mfp->mf_fname = NULL;
@@ -249,53 +242,45 @@ mf_close_file (
   }
 }
 
-/*
- * Set new size for a memfile.  Used when block 0 of a swapfile has been read
- * and the size it indicates differs from what was guessed.
- */
+/// Set new size for a memfile. Used when block 0 of a swapfile has been read
+/// and the size it indicates differs from what was guessed.
 void mf_new_page_size(memfile_T *mfp, unsigned new_size)
 {
-  /* Correct the memory used for block 0 to the new size, because it will be
-   * freed with that size later on. */
+  // Correct the memory used for block 0 to the new size, because it will be
+  // freed with that size later on.
   total_mem_used += new_size - mfp->mf_page_size;
   mfp->mf_page_size = new_size;
 }
 
-/*
- * get a new block
- *
- *   negative: TRUE if negative block number desired (data block)
- */
+/// Get a new block
+/// 
+/// @param negative    TRUE if negative block number desired (data block)
+/// @param page_count  Desired number of pages.
 bhdr_T *mf_new(memfile_T *mfp, int negative, int page_count)
 {
-  bhdr_T      *hp;      /* new bhdr_T */
-  bhdr_T      *freep;   /* first block in free list */
+  bhdr_T      *hp;      // new block
+  bhdr_T      *freep;   // first block in free list
   char_u      *p;
 
-  /*
-   * If we reached the maximum size for the used memory blocks, release one
-   * If a bhdr_T is returned, use it and adjust the page_count if necessary.
-   */
+  // If we reached the maximum size for the used memory blocks, release one.
+  // If a bhdr_T is returned, use it and adjust the page_count if necessary.
+  // If no bhdr_T is returned, a new one will be created.
   hp = mf_release(mfp, page_count);
 
-  /*
-   * Decide on the number to use:
-   * If there is a free block, use its number.
-   * Otherwise use mf_block_min for a negative number, mf_block_max for
-   * a positive number.
-   */
+  // Decide on the number to use:
+  // If there is a free block, use its number.
+  // Otherwise use mf_block_min for a negative number, mf_block_max for
+  // a positive number.
   freep = mfp->mf_free_first;
   if (!negative && freep != NULL && freep->bh_page_count >= page_count) {
-    /*
-     * If the block in the free list has more pages, take only the number
-     * of pages needed and allocate a new bhdr_T with data
-     *
-     * If the number of pages matches and mf_release() did not return a
-     * bhdr_T, use the bhdr_T from the free list and allocate the data
-     *
-     * If the number of pages matches and mf_release() returned a bhdr_T,
-     * just use the number and free the bhdr_T from the free list
-     */
+    // If the block in the free list has more pages, take only the number
+    // of pages needed and allocate a new bhdr_T with data.
+    // 
+    // If the number of pages matches and mf_release() did not return a
+    // bhdr_T, use the bhdr_T from the free list and allocate the data.
+    // 
+    // If the number of pages matches and mf_release() returned a bhdr_T,
+    // just use the number and free the bhdr_T from the free list
     if (freep->bh_page_count > page_count) {
       if (hp == NULL) {
         hp = mf_alloc_bhdr(mfp, page_count);
@@ -303,16 +288,16 @@ bhdr_T *mf_new(memfile_T *mfp, int negative, int page_count)
       hp->bh_bnum = freep->bh_bnum;
       freep->bh_bnum += page_count;
       freep->bh_page_count -= page_count;
-    } else if (hp == NULL) {      /* need to allocate memory for this block */
+    } else if (hp == NULL) {    // need to allocate memory for this block
       p = xmalloc(mfp->mf_page_size * page_count);
       hp = mf_rem_free(mfp);
       hp->bh_data = p;
-    } else {              /* use the number, remove entry from free list */
+    } else {                    // use the number, remove entry from free list
       freep = mf_rem_free(mfp);
       hp->bh_bnum = freep->bh_bnum;
       free(freep);
     }
-  } else {    /* get a new number */
+  } else {                      // get a new number
     if (hp == NULL) {
       hp = mf_alloc_bhdr(mfp, page_count);
     }
@@ -324,49 +309,43 @@ bhdr_T *mf_new(memfile_T *mfp, int negative, int page_count)
       mfp->mf_blocknr_max += page_count;
     }
   }
-  hp->bh_flags = BH_LOCKED | BH_DIRTY;          /* new block is always dirty */
+  hp->bh_flags = BH_LOCKED | BH_DIRTY;    // new block is always dirty
   mfp->mf_dirty = TRUE;
   hp->bh_page_count = page_count;
   mf_ins_used(mfp, hp);
   mf_ins_hash(mfp, hp);
 
-  /*
-   * Init the data to all zero, to avoid reading uninitialized data.
-   * This also avoids that the passwd file ends up in the swap file!
-   */
+  // Init the data to all zero, to avoid reading uninitialized data.
+  // This also avoids that the passwd file ends up in the swap file!
   (void)memset((char *)(hp->bh_data), 0,
       (size_t)mfp->mf_page_size * page_count);
 
   return hp;
 }
 
-/*
- * Get existing block "nr" with "page_count" pages.
- *
- * Note: The caller should first check a negative nr with mf_trans_del()
- */
+// Get existing block "nr" with "page_count" pages.
+//
+// Caller should first check a negative nr with mf_trans_del().
+//
+// @return  NULL if not found
 bhdr_T *mf_get(memfile_T *mfp, blocknr_T nr, int page_count)
 {
   bhdr_T    *hp;
-  /* doesn't exist */
+  // check block number exists
   if (nr >= mfp->mf_blocknr_max || nr <= mfp->mf_blocknr_min)
     return NULL;
 
-  /*
-   * see if it is in the cache
-   */
+  // see if it is in the cache
   hp = mf_find_hash(mfp, nr);
-  if (hp == NULL) {     /* not in the hash list */
-    if (nr < 0 || nr >= mfp->mf_infile_count)       /* can't be in the file */
+  if (hp == NULL) {                             // not in the hash list
+    if (nr < 0 || nr >= mfp->mf_infile_count)   // can't be in the file
       return NULL;
 
-    /* could check here if the block is in the free list */
+    // could check here if the block is in the free list
 
-    /*
-     * Check if we need to flush an existing block.
-     * If so, use that block.
-     * If not, allocate a new block.
-     */
+    // Check if we need to flush an existing block.
+    // If so, use that block.
+    // If not, allocate a new block.
     hp = mf_release(mfp, page_count);
     if (hp == NULL) {
       hp = mf_alloc_bhdr(mfp, page_count);
@@ -375,30 +354,26 @@ bhdr_T *mf_get(memfile_T *mfp, blocknr_T nr, int page_count)
     hp->bh_bnum = nr;
     hp->bh_flags = 0;
     hp->bh_page_count = page_count;
-    if (mf_read(mfp, hp) == FAIL) {         /* cannot read the block! */
+    if (mf_read(mfp, hp) == FAIL) {             // cannot read the block
       mf_free_bhdr(hp);
       return NULL;
     }
   } else {
-    mf_rem_used(mfp, hp);       /* remove from list, insert in front below */
+    mf_rem_used(mfp, hp);       // remove from list, insert in front below
     mf_rem_hash(mfp, hp);
   }
 
   hp->bh_flags |= BH_LOCKED;
-  mf_ins_used(mfp, hp);         /* put in front of used list */
-  mf_ins_hash(mfp, hp);         /* put in front of hash list */
+  mf_ins_used(mfp, hp);         // put in front of used list
+  mf_ins_hash(mfp, hp);         // put in front of hash list
 
   return hp;
 }
 
-/*
- * release the block *hp
- *
- *   dirty: Block must be written to file later
- *   infile: Block should be in file (needed for recovery)
- *
- *  no return value, function cannot fail
- */
+/// Release the block *hp.
+/// 
+/// @param dirty   Block must be written to file later.
+/// @param infile  Block should be in file (needed for recovery).
 void mf_put(memfile_T *mfp, bhdr_T *hp, int dirty, int infile)
 {
   int flags;
@@ -414,37 +389,36 @@ void mf_put(memfile_T *mfp, bhdr_T *hp, int dirty, int infile)
   }
   hp->bh_flags = flags;
   if (infile)
-    mf_trans_add(mfp, hp);          /* may translate negative in positive nr */
+    mf_trans_add(mfp, hp);      // may translate negative in positive nr
 }
 
-/*
- * block *hp is no longer in used, may put it in the free list of memfile *mfp
- */
+/// Signal block as no longer used (may put it in the free list).
 void mf_free(memfile_T *mfp, bhdr_T *hp)
 {
-  free(hp->bh_data);        /* free the memory */
-  mf_rem_hash(mfp, hp);         /* get *hp out of the hash list */
-  mf_rem_used(mfp, hp);         /* get *hp out of the used list */
+  free(hp->bh_data);            // free data
+  mf_rem_hash(mfp, hp);         // get *hp out of the hash list
+  mf_rem_used(mfp, hp);         // get *hp out of the used list
   if (hp->bh_bnum < 0) {
-    free(hp);               /* don't want negative numbers in free list */
+    free(hp);                   // don't want negative numbers in free list
     mfp->mf_neg_count--;
   } else
-    mf_ins_free(mfp, hp);       /* put *hp in the free list */
+    mf_ins_free(mfp, hp);       // put *hp in the free list
 }
 
-/*
- * Sync the memory file *mfp to disk.
- * Flags:
- *  MFS_ALL	If not given, blocks with negative numbers are not synced,
- *		even when they are dirty!
- *  MFS_STOP	Stop syncing when a character becomes available, but sync at
- *		least one block.
- *  MFS_FLUSH	Make sure buffers are flushed to disk, so they will survive a
- *		system crash.
- *  MFS_ZERO	Only write block 0.
- *
- * Return FAIL for failure, OK otherwise
- */
+/// Sync memory file to disk.
+///
+/// @param flags  MFS_ALL    If not given, blocks with negative numbers are not
+///                          synced, even when they are dirty.
+///               MFS_STOP   Stop syncing when a character becomes available,
+///                          but sync at least one block.
+///               MFS_FLUSH  Make sure buffers are flushed to disk, so they will
+///                          survive a system crash.
+///               MFS_ZERO   Only write block 0.
+/// 
+/// @return FAIL  If failure. Possible causes:
+///               - No file (nothing to do).
+///               - Write error (probably full disk).
+///         OK    Otherwise.
 int mf_sync(memfile_T *mfp, int flags)
 {
   int status;
@@ -454,21 +428,18 @@ int mf_sync(memfile_T *mfp, int flags)
 #endif
   int got_int_save = got_int;
 
-  if (mfp->mf_fd < 0) {     /* there is no file, nothing to do */
+  if (mfp->mf_fd < 0) {         // there is no file, nothing to do
     mfp->mf_dirty = FALSE;
     return FAIL;
   }
 
-  /* Only a CTRL-C while writing will break us here, not one typed
-   * previously. */
+  // Only a CTRL-C while writing will break us here, not one typed previously.
   got_int = FALSE;
 
-  /*
-   * sync from last to first (may reduce the probability of an inconsistent
-   * file) If a write fails, it is very likely caused by a full filesystem.
-   * Then we only try to write blocks within the existing file. If that also
-   * fails then we give up.
-   */
+  // Sync from last to first (may reduce the probability of an inconsistent
+  // file). If a write fails, it is very likely caused by a full filesystem.
+  // Then we only try to write blocks within the existing file. If that also
+  // fails then we give up.
   status = OK;
   for (hp = mfp->mf_used_last; hp != NULL; hp = hp->bh_prev)
     if (((flags & MFS_ALL) || hp->bh_bnum >= 0)
@@ -478,12 +449,11 @@ int mf_sync(memfile_T *mfp, int flags)
       if ((flags & MFS_ZERO) && hp->bh_bnum != 0)
         continue;
       if (mf_write(mfp, hp) == FAIL) {
-        if (status == FAIL)             /* double error: quit syncing */
+        if (status == FAIL)     // double error: quit syncing
           break;
         status = FAIL;
       }
-      if (flags & MFS_STOP) {
-        /* Stop when char available now. */
+      if (flags & MFS_STOP) {   // Stop when char available now.
         if (ui_char_avail())
           break;
       } else
@@ -492,10 +462,8 @@ int mf_sync(memfile_T *mfp, int flags)
         break;
     }
 
-  /*
-   * If the whole list is flushed, the memfile is not dirty anymore.
-   * In case of an error this flag is also set, to avoid trying all the time.
-   */
+  // If the whole list is flushed, the memfile is not dirty anymore.
+  // In case of an error, dirty flag is also set, to avoid trying all the time.
   if (hp == NULL || status == FAIL)
     mfp->mf_dirty = FALSE;
 
@@ -507,8 +475,8 @@ int mf_sync(memfile_T *mfp, int flags)
         status = FAIL;
     } else
 # endif
-    /* OpenNT is strictly POSIX (Benzinger) */
-    /* Tandem/Himalaya NSK-OSS doesn't have sync() */
+    // OpenNT is strictly POSIX (Benzinger).
+    // Tandem/Himalaya NSK-OSS doesn't have sync()
 # if defined(__OPENNT) || defined(__TANDEM)
     fflush(NULL);
 # else
@@ -516,10 +484,8 @@ int mf_sync(memfile_T *mfp, int flags)
 # endif
 #endif
 # ifdef SYNC_DUP_CLOSE
-    /*
-     * Win32 is a bit more work: Duplicate the file handle and close it.
-     * This should flush the file to disk.
-     */
+    // Win32 is a bit more work: Duplicate the file handle and close it.
+    // This should flush the file to disk.
     if ((fd = dup(mfp->mf_fd)) >= 0)
       close(fd);
 # endif
@@ -530,11 +496,8 @@ int mf_sync(memfile_T *mfp, int flags)
   return status;
 }
 
-/*
- * For all blocks in memory file *mfp that have a positive block number set
- * the dirty flag.  These are blocks that need to be written to a newly
- * created swapfile.
- */
+/// Set dirty flag for all blocks in memory file with a positive block number.
+/// These are blocks that need to be written to a newly created swapfile.
 void mf_set_dirty(memfile_T *mfp)
 {
   bhdr_T      *hp;
@@ -545,39 +508,31 @@ void mf_set_dirty(memfile_T *mfp)
   mfp->mf_dirty = TRUE;
 }
 
-/*
- * insert block *hp in front of hashlist of memfile *mfp
- */
+/// Insert block in front of memfile's hash list.
 static void mf_ins_hash(memfile_T *mfp, bhdr_T *hp)
 {
   mf_hash_add_item(&mfp->mf_hash, (mf_hashitem_T *)hp);
 }
 
-/*
- * remove block *hp from hashlist of memfile list *mfp
- */
+/// Remove block from memfile's hash list.
 static void mf_rem_hash(memfile_T *mfp, bhdr_T *hp)
 {
   mf_hash_rem_item(&mfp->mf_hash, (mf_hashitem_T *)hp);
 }
 
-/*
- * look in hash lists of memfile *mfp for block header with number 'nr'
- */
+/// Lookup block with number "nr" in memfile's hash list.
 static bhdr_T *mf_find_hash(memfile_T *mfp, blocknr_T nr)
 {
   return (bhdr_T *)mf_hash_find(&mfp->mf_hash, nr);
 }
 
-/*
- * insert block *hp in front of used list of memfile *mfp
- */
+/// Insert block at the front of memfile's used list.
 static void mf_ins_used(memfile_T *mfp, bhdr_T *hp)
 {
   hp->bh_next = mfp->mf_used_first;
   mfp->mf_used_first = hp;
   hp->bh_prev = NULL;
-  if (hp->bh_next == NULL)          /* list was empty, adjust last pointer */
+  if (hp->bh_next == NULL)      // list was empty, adjust last pointer
     mfp->mf_used_last = hp;
   else
     hp->bh_next->bh_prev = hp;
@@ -585,52 +540,54 @@ static void mf_ins_used(memfile_T *mfp, bhdr_T *hp)
   total_mem_used += hp->bh_page_count * mfp->mf_page_size;
 }
 
-/*
- * remove block *hp from used list of memfile *mfp
- */
+/// Remove block from memfile's used list.
 static void mf_rem_used(memfile_T *mfp, bhdr_T *hp)
 {
-  if (hp->bh_next == NULL)          /* last block in used list */
+  if (hp->bh_next == NULL)                 // last block in used list
     mfp->mf_used_last = hp->bh_prev;
   else
     hp->bh_next->bh_prev = hp->bh_prev;
-  if (hp->bh_prev == NULL)          /* first block in used list */
+
+  if (hp->bh_prev == NULL)                 // first block in used list
     mfp->mf_used_first = hp->bh_next;
   else
     hp->bh_prev->bh_next = hp->bh_next;
+
   mfp->mf_used_count -= hp->bh_page_count;
   total_mem_used -= hp->bh_page_count * mfp->mf_page_size;
 }
 
-/*
- * Release the least recently used block from the used list if the number
- * of used memory blocks gets to big.
- *
- * Return the block header to the caller, including the memory block, so
- * it can be re-used. Make sure the page_count is right.
- */
+/// Try to release the least recently used block from the used list if the
+/// number of used memory blocks gets too big.
+/// 
+/// @return  The block header, when release needed and possible.
+///              Resulting block header includes memory block, so it can be
+///              reused.  Page count is checked to be right.
+///          NULL, when release not needed, or not possible.
+///              Not needed when number of blocks less than allowed maximum and
+///              total memory used below 'maxmemtot'.
+///              Not possible when:
+///              - Called while closing file.
+///              - Tried to create swap file but couldn't.
+///              - All blocks are locked.
+///              - Unlocked dirty block found, but flush failed.
 static bhdr_T *mf_release(memfile_T *mfp, int page_count)
 {
   bhdr_T      *hp;
   int need_release;
 
-  /* don't release while in mf_close_file() */
+  // don't release while in mf_close_file()
   if (mf_dont_release)
     return NULL;
 
-  /*
-   * Need to release a block if the number of blocks for this memfile is
-   * higher than the maximum or total memory used is over 'maxmemtot'
-   */
+  /// Need to release a block if the number of blocks for this memfile is
+  /// higher than the maximum one or total memory used is over 'maxmemtot'.
   need_release = ((mfp->mf_used_count >= mfp->mf_used_count_max)
                   || (total_mem_used >> 10) >= (long_u)p_mmt);
 
-  /*
-   * Try to create a swap file if the amount of memory used is getting too
-   * high.
-   */
+  /// Try to create swap file if the amount of memory used is getting too high.
   if (mfp->mf_fd < 0 && need_release && p_uc) {
-    /* find for which buffer this memfile is */
+    // find for which buffer this memfile is
     buf_T *buf = NULL;
     FOR_ALL_BUFFERS(bp) {
       if (bp->b_ml.ml_mfp == mfp) {
@@ -643,37 +600,30 @@ static bhdr_T *mf_release(memfile_T *mfp, int page_count)
     }
   }
 
-  /*
-   * don't release a block if
-   *	there is no file for this memfile
-   * or
-   *	the number of blocks for this memfile is lower than the maximum
-   *	  and
-   *	total memory used is not up to 'maxmemtot'
-   */
+  /// Don't release a block if:
+  ///     there is no file for this memfile
+  ///     or
+  ///         the number of blocks for this memfile is lower than the maximum
+  ///         and
+  ///         total memory used is not up to 'maxmemtot'
   if (mfp->mf_fd < 0 || !need_release)
     return NULL;
 
   for (hp = mfp->mf_used_last; hp != NULL; hp = hp->bh_prev)
     if (!(hp->bh_flags & BH_LOCKED))
       break;
-  if (hp == NULL)       /* not a single one that can be released */
+  if (hp == NULL)       // not a single one that can be released
     return NULL;
 
-  /*
-   * If the block is dirty, write it.
-   * If the write fails we don't free it.
-   */
+  // If the block is dirty, write it.
+  // If the write fails we don't free it.
   if ((hp->bh_flags & BH_DIRTY) && mf_write(mfp, hp) == FAIL)
     return NULL;
 
   mf_rem_used(mfp, hp);
   mf_rem_hash(mfp, hp);
 
-  /*
-   * If a bhdr_T is returned, make sure that the page_count of bh_data is
-   * right
-   */
+  /// Make sure page_count of bh_data is right.
   if (hp->bh_page_count != page_count) {
     free(hp->bh_data);
     hp->bh_data = xmalloc(mfp->mf_page_size * page_count);
@@ -682,12 +632,12 @@ static bhdr_T *mf_release(memfile_T *mfp, int page_count)
   return hp;
 }
 
-/*
- * release as many blocks as possible
- * Used in case of out of memory
- *
- * return TRUE if any memory was released
- */
+/// Release as many blocks as possible.
+///
+/// Used in case of out of memory
+/// 
+/// @return  TRUE   If any memory was released.
+///          FALSE  If not.
 int mf_release_all(void)
 {
   memfile_T   *mfp;
@@ -697,11 +647,11 @@ int mf_release_all(void)
   FOR_ALL_BUFFERS(buf) {
     mfp = buf->b_ml.ml_mfp;
     if (mfp != NULL) {
-      /* If no swap file yet, may open one */
+      // If no swap file yet, may open one.
       if (mfp->mf_fd < 0 && buf->b_may_swap)
         ml_open_file(buf);
 
-      /* only if there is a swapfile */
+      // Flush as many blocks as possible, only if there is a swapfile.
       if (mfp->mf_fd >= 0) {
         for (hp = mfp->mf_used_last; hp != NULL; ) {
           if (!(hp->bh_flags & BH_LOCKED)
@@ -710,7 +660,7 @@ int mf_release_all(void)
             mf_rem_used(mfp, hp);
             mf_rem_hash(mfp, hp);
             mf_free_bhdr(hp);
-            hp = mfp->mf_used_last;             /* re-start, list was changed */
+            hp = mfp->mf_used_last;    // restart, list was changed
             retval = TRUE;
           } else
             hp = hp->bh_prev;
@@ -721,9 +671,7 @@ int mf_release_all(void)
   return retval;
 }
 
-/*
- * Allocate a block header and a block of memory for it
- */
+/// Allocate a block header and a block of memory for it.
 static bhdr_T *mf_alloc_bhdr(memfile_T *mfp, int page_count)
 {
   bhdr_T *hp = xmalloc(sizeof(bhdr_T));
@@ -733,28 +681,23 @@ static bhdr_T *mf_alloc_bhdr(memfile_T *mfp, int page_count)
   return hp;
 }
 
-/*
- * Free a block header and the block of memory for it
- */
+/// Free a block header and its block memory.
 static void mf_free_bhdr(bhdr_T *hp)
 {
   free(hp->bh_data);
   free(hp);
 }
 
-/*
- * insert entry *hp in the free list
- */
+/// Insert a block in the free list.
 static void mf_ins_free(memfile_T *mfp, bhdr_T *hp)
 {
   hp->bh_next = mfp->mf_free_first;
   mfp->mf_free_first = hp;
 }
 
-/*
- * remove the first entry from the free list and return a pointer to it
- * Note: caller must check that mfp->mf_free_first is not NULL!
- */
+/// Remove the first block in the free list and return it.
+///
+/// Caller must check that mfp->mf_free_first is not NULL.
 static bhdr_T *mf_rem_free(memfile_T *mfp)
 {
   bhdr_T      *hp;
@@ -764,18 +707,19 @@ static bhdr_T *mf_rem_free(memfile_T *mfp)
   return hp;
 }
 
-/*
- * read a block from disk
- *
- * Return FAIL for failure, OK otherwise
- */
+/// Read a block from disk.
+/// 
+/// @return  OK    On success.
+///          FAIL  On failure. Could be:
+///                - No file.
+///                - Error reading file.
 static int mf_read(memfile_T *mfp, bhdr_T *hp)
 {
   off_t offset;
   unsigned page_size;
   unsigned size;
 
-  if (mfp->mf_fd < 0)       /* there is no file, can't read */
+  if (mfp->mf_fd < 0)       // there is no file, can't read
     return FAIL;
 
   page_size = mfp->mf_page_size;
@@ -793,40 +737,41 @@ static int mf_read(memfile_T *mfp, bhdr_T *hp)
   return OK;
 }
 
-/*
- * write a block to disk
- *
- * Return FAIL for failure, OK otherwise
- */
+/// Write a block to disk.
+/// 
+/// @return  OK    On success.
+///          FAIL  On failure. Could be:
+///                - No file.
+///                - Could not translate negative block number to positive.
+///                - Seek error in swap file.
+///                - Write error in swap file.
 static int mf_write(memfile_T *mfp, bhdr_T *hp)
 {
-  off_t offset;             /* offset in the file */
-  blocknr_T nr;             /* block nr which is being written */
-  bhdr_T      *hp2;
-  unsigned page_size;       /* number of bytes in a page */
-  unsigned page_count;      /* number of pages written */
-  unsigned size;            /* number of bytes written */
-
-  if (mfp->mf_fd < 0)       /* there is no file, can't write */
+  off_t offset;             // offset in the file
+  blocknr_T nr;             // block nr which is being written
+  bhdr_T *hp2;
+  unsigned page_size;       // number of bytes in a page
+  unsigned page_count;      // number of pages written
+  unsigned size;            // number of bytes written
+
+  if (mfp->mf_fd < 0)       // there is no file, can't write
     return FAIL;
 
-  if (hp->bh_bnum < 0)          /* must assign file block number */
+  if (hp->bh_bnum < 0)      // must assign file block number
     if (mf_trans_add(mfp, hp) == FAIL)
       return FAIL;
 
   page_size = mfp->mf_page_size;
 
-  /*
-   * We don't want gaps in the file. Write the blocks in front of *hp
-   * to extend the file.
-   * If block 'mf_infile_count' is not in the hash list, it has been
-   * freed. Fill the space in the file with data from the current block.
-   */
+  /// We don't want gaps in the file. Write the blocks in front of *hp
+  /// to extend the file.
+  /// If block 'mf_infile_count' is not in the hash list, it has been
+  /// freed. Fill the space in the file with data from the current block.
   for (;; ) {
     nr = hp->bh_bnum;
-    if (nr > mfp->mf_infile_count) {            /* beyond end of file */
+    if (nr > mfp->mf_infile_count) {            // beyond end of file
       nr = mfp->mf_infile_count;
-      hp2 = mf_find_hash(mfp, nr);              /* NULL caught below */
+      hp2 = mf_find_hash(mfp, nr);              // NULL caught below
     } else
       hp2 = hp;
 
@@ -835,39 +780,36 @@ static int mf_write(memfile_T *mfp, bhdr_T *hp)
       PERROR(_("E296: Seek error in swap file write"));
       return FAIL;
     }
-    if (hp2 == NULL)                /* freed block, fill with dummy data */
+    if (hp2 == NULL)                // freed block, fill with dummy data
       page_count = 1;
     else
       page_count = hp2->bh_page_count;
     size = page_size * page_count;
     if (mf_write_block(mfp, hp2 == NULL ? hp : hp2, offset, size) == FAIL) {
-      /*
-       * Avoid repeating the error message, this mostly happens when the
-       * disk is full. We give the message again only after a successful
-       * write or when hitting a key. We keep on trying, in case some
-       * space becomes available.
-       */
+      /// Avoid repeating the error message, this mostly happens when the
+      /// disk is full. We give the message again only after a successful
+      /// write or when hitting a key. We keep on trying, in case some
+      /// space becomes available.
       if (!did_swapwrite_msg)
         EMSG(_("E297: Write error in swap file"));
       did_swapwrite_msg = TRUE;
       return FAIL;
     }
     did_swapwrite_msg = FALSE;
-    if (hp2 != NULL)                        /* written a non-dummy block */
+    if (hp2 != NULL)                               // written a non-dummy block
       hp2->bh_flags &= ~BH_DIRTY;
-    /* appended to the file */
-    if (nr + (blocknr_T)page_count > mfp->mf_infile_count)
+    if (nr + (blocknr_T)page_count > mfp->mf_infile_count)  // appended to file
       mfp->mf_infile_count = nr + page_count;
-    if (nr == hp->bh_bnum)                  /* written the desired block */
+    if (nr == hp->bh_bnum)                         // written the desired block
       break;
   }
   return OK;
 }
 
-/*
- * Write block "hp" with data size "size" to file "mfp->mf_fd".
- * Return FAIL or OK.
- */
+/// Write block to memfile's file.
+///
+/// @return  OK    On success.
+///          FAIL  On failure.
 static int mf_write_block(memfile_T *mfp, bhdr_T *hp, off_t offset, unsigned size)
 {
   char_u      *data = hp->bh_data;
@@ -879,35 +821,30 @@ static int mf_write_block(memfile_T *mfp, bhdr_T *hp, off_t offset, unsigned siz
   return result;
 }
 
-/*
- * Make block number for *hp positive and add it to the translation list
- *
- * Return FAIL for failure, OK otherwise
- */
+/// Make block number positive and add it to the translation list.
+/// 
+/// @return  OK    On success.
+///          FAIL  On failure.
 static int mf_trans_add(memfile_T *mfp, bhdr_T *hp)
 {
   bhdr_T      *freep;
   blocknr_T new_bnum;
   int page_count;
 
-  if (hp->bh_bnum >= 0)                     /* it's already positive */
+  if (hp->bh_bnum >= 0)                     // it's already positive
     return OK;
 
   NR_TRANS *np = xmalloc(sizeof(NR_TRANS));
 
-  /*
-   * Get a new number for the block.
-   * If the first item in the free list has sufficient pages, use its number
-   * Otherwise use mf_blocknr_max.
-   */
+  // Get a new number for the block.
+  // If the first item in the free list has sufficient pages, use its number.
+  // Otherwise use mf_blocknr_max.
   freep = mfp->mf_free_first;
   page_count = hp->bh_page_count;
   if (freep != NULL && freep->bh_page_count >= page_count) {
     new_bnum = freep->bh_bnum;
-    /*
-     * If the page count of the free block was larger, reduce it.
-     * If the page count matches, remove the block from the free list
-     */
+    // If the page count of the free block was larger, reduce it.
+    // If the page count matches, remove the block from the free list.
     if (freep->bh_page_count > page_count) {
       freep->bh_bnum += page_count;
       freep->bh_page_count -= page_count;
@@ -920,24 +857,23 @@ static int mf_trans_add(memfile_T *mfp, bhdr_T *hp)
     mfp->mf_blocknr_max += page_count;
   }
 
-  np->nt_old_bnum = hp->bh_bnum;            /* adjust number */
+  np->nt_old_bnum = hp->bh_bnum;            // adjust number
   np->nt_new_bnum = new_bnum;
 
-  mf_rem_hash(mfp, hp);                     /* remove from old hash list */
+  mf_rem_hash(mfp, hp);                     // remove from old hash list
   hp->bh_bnum = new_bnum;
-  mf_ins_hash(mfp, hp);                     /* insert in new hash list */
+  mf_ins_hash(mfp, hp);                     // insert in new hash list
 
-  /* Insert "np" into "mf_trans" hashtable with key "np->nt_old_bnum" */
+  // Insert "np" into "mf_trans" hashtable with key "np->nt_old_bnum".
   mf_hash_add_item(&mfp->mf_trans, (mf_hashitem_T *)np);
 
   return OK;
 }
 
-/*
- * Lookup a translation from the trans lists and delete the entry
- *
- * Return the positive new number when found, the old number when not found
- */
+/// Lookup translation from trans list and delete the entry.
+/// 
+/// @return  The positive new number  When found.
+///          The old number           When not found.
 blocknr_T mf_trans_del(memfile_T *mfp, blocknr_T old_nr)
 {
   NR_TRANS    *np;
@@ -945,13 +881,13 @@ blocknr_T mf_trans_del(memfile_T *mfp, blocknr_T old_nr)
 
   np = (NR_TRANS *)mf_hash_find(&mfp->mf_trans, old_nr);
 
-  if (np == NULL)               /* not found */
+  if (np == NULL)    // not found
     return old_nr;
 
   mfp->mf_neg_count--;
   new_bnum = np->nt_new_bnum;
 
-  /* remove entry from the trans list */
+  // remove entry from the trans list
   mf_hash_rem_item(&mfp->mf_trans, (mf_hashitem_T *)np);
 
   free(np);
@@ -959,20 +895,19 @@ blocknr_T mf_trans_del(memfile_T *mfp, blocknr_T old_nr)
   return new_bnum;
 }
 
-/*
- * Set mfp->mf_ffname according to mfp->mf_fname and some other things.
- * Only called when creating or renaming the swapfile.	Either way it's a new
- * name so we must work out the full path name.
- */
+/// Set full file name of memfile's swapfile, out of simple file name and some
+/// other considerations.
+///
+/// Only called when creating or renaming the swapfile. Either way it's a new
+/// name so we must work out the full path name.
 void mf_set_ffname(memfile_T *mfp)
 {
   mfp->mf_ffname = FullName_save(mfp->mf_fname, FALSE);
 }
 
-/*
- * Make the name of the file used for the memfile a full path.
- * Used before doing a :cd
- */
+/// Make name of memfile's swapfile a full path.
+///
+/// Used before doing a :cd
 void mf_fullname(memfile_T *mfp)
 {
   if (mfp != NULL && mfp->mf_fname != NULL && mfp->mf_ffname != NULL) {
@@ -982,19 +917,17 @@ void mf_fullname(memfile_T *mfp)
   }
 }
 
-/*
- * return TRUE if there are any translations pending for 'mfp'
- */
+/// Return TRUE if there are any translations pending for memfile.
 int mf_need_trans(memfile_T *mfp)
 {
   return mfp->mf_fname != NULL && mfp->mf_neg_count > 0;
 }
 
-/*
- * Open a swap file for a memfile.
- * The "fname" must be in allocated memory, and is consumed (also when an
- * error occurs).
- */
+/// Open memfile's swapfile.
+///
+/// "fname" must be in allocated memory, and is consumed (also when error).
+///
+/// @param  flags  Flags for open().
 static void 
 mf_do_open (
     memfile_T *mfp,
@@ -1002,35 +935,24 @@ mf_do_open (
     int flags                      /* flags for open() */
 )
 {
+  // fname cannot be NameBuff, because it must have been allocated.
   mfp->mf_fname = fname;
-
-  /*
-   * Get the full path name before the open, because this is
-   * not possible after the open on the Amiga.
-   * fname cannot be NameBuff, because it must have been allocated.
-   */
   mf_set_ffname(mfp);
 
-  /*
-   * Extra security check: When creating a swap file it really shouldn't
-   * exist yet.  If there is a symbolic link, this is most likely an attack.
-   */
+  /// Extra security check: When creating a swap file it really shouldn't
+  /// exist yet. If there is a symbolic link, this is most likely an attack.
   FileInfo file_info;
   if ((flags & O_CREAT)
       && os_fileinfo_link((char *)mfp->mf_fname, &file_info)) {
     mfp->mf_fd = -1;
     EMSG(_("E300: Swap file already exists (symlink attack?)"));
   } else {
-    /*
-     * try to open the file
-     */
+    // try to open the file
     flags |= O_NOFOLLOW;
     mfp->mf_fd = mch_open_rw((char *)mfp->mf_fname, flags);
   }
 
-  /*
-   * If the file cannot be opened, use memory only
-   */
+  // If the file cannot be opened, use memory only
   if (mfp->mf_fd < 0) {
     free(mfp->mf_fname);
     free(mfp->mf_ffname);
@@ -1045,25 +967,21 @@ mf_do_open (
 #ifdef HAVE_SELINUX
     mch_copy_sec(fname, mfp->mf_fname);
 #endif
-    mch_hide(mfp->mf_fname);        /* try setting the 'hidden' flag */
+    mch_hide(mfp->mf_fname);        // try setting the 'hidden' flag
   }
 }
 
-/*
- * Implementation of mf_hashtab_T follows.
- */
+// 
+// Implementation of mf_hashtab_T.
+// 
 
-/*
- * The number of buckets in the hashtable is increased by a factor of
- * MHT_GROWTH_FACTOR when the average number of items per bucket
- * exceeds 2 ^ MHT_LOG_LOAD_FACTOR.
- */
+/// The number of buckets in the hashtable is increased by a factor of
+/// MHT_GROWTH_FACTOR when the average number of items per bucket
+/// exceeds 2 ^ MHT_LOG_LOAD_FACTOR.
 #define MHT_LOG_LOAD_FACTOR 6
-#define MHT_GROWTH_FACTOR   2   /* must be a power of two */
+#define MHT_GROWTH_FACTOR   2   // must be a power of two
 
-/*
- * Initialize an empty hash table.
- */
+/// Initialize an empty hash table.
 static void mf_hash_init(mf_hashtab_T *mht)
 {
   memset(mht, 0, sizeof(mf_hashtab_T));
@@ -1071,19 +989,15 @@ static void mf_hash_init(mf_hashtab_T *mht)
   mht->mht_mask = MHT_INIT_SIZE - 1;
 }
 
-/*
- * Free the array of a hash table.  Does not free the items it contains!
- * The hash table must not be used again without another mf_hash_init() call.
- */
+/// Free the array of a hash table. Does not free the items it contains!
+/// The hash table must not be used again without another mf_hash_init() call.
 static void mf_hash_free(mf_hashtab_T *mht)
 {
   if (mht->mht_buckets != mht->mht_small_buckets)
     free(mht->mht_buckets);
 }
 
-/*
- * Free the array of a hash table and all the items it contains.
- */
+/// Free the array of a hash table and all the items it contains.
 static void mf_hash_free_all(mf_hashtab_T *mht)
 {
   long_u idx;
@@ -1099,10 +1013,9 @@ static void mf_hash_free_all(mf_hashtab_T *mht)
   mf_hash_free(mht);
 }
 
-/*
- * Find "key" in hashtable "mht".
- * Returns a pointer to a mf_hashitem_T or NULL if the item was not found.
- */
+/// Find by key.
+///
+/// @return  A pointer to a mf_hashitem_T or NULL if the item was not found.
 static mf_hashitem_T *mf_hash_find(mf_hashtab_T *mht, blocknr_T key)
 {
   mf_hashitem_T   *mhi;
@@ -1114,10 +1027,7 @@ static mf_hashitem_T *mf_hash_find(mf_hashtab_T *mht, blocknr_T key)
   return mhi;
 }
 
-/*
- * Add item "mhi" to hashtable "mht".
- * "mhi" must not be NULL.
- */
+/// Add item to hashtable. Item must not be NULL.
 static void mf_hash_add_item(mf_hashtab_T *mht, mf_hashitem_T *mhi)
 {
   long_u idx;
@@ -1131,20 +1041,15 @@ static void mf_hash_add_item(mf_hashtab_T *mht, mf_hashitem_T *mhi)
 
   mht->mht_count++;
 
-  /*
-   * Grow hashtable when we have more thank 2^MHT_LOG_LOAD_FACTOR
-   * items per bucket on average
-   */
+  /// Grow hashtable when we have more thank 2^MHT_LOG_LOAD_FACTOR
+  /// items per bucket on average.
   if (mht->mht_fixed == 0
       && (mht->mht_count >> MHT_LOG_LOAD_FACTOR) > mht->mht_mask) {
     mf_hash_grow(mht);
   }
 }
 
-/*
- * Remove item "mhi" from hashtable "mht".
- * "mhi" must not be NULL and must have been inserted into "mht".
- */
+/// Remove item from hashtable. Item must be non NULL and within hashtable.
 static void mf_hash_rem_item(mf_hashtab_T *mht, mf_hashitem_T *mhi)
 {
   if (mhi->mhi_prev == NULL)
@@ -1157,14 +1062,12 @@ static void mf_hash_rem_item(mf_hashtab_T *mht, mf_hashitem_T *mhi)
 
   mht->mht_count--;
 
-  /* We could shrink the table here, but it typically takes little memory,
-   * so why bother?  */
+  // We could shrink the table here, but it typically takes little memory,
+  // so why bother?
 }
 
-/*
- * Increase number of buckets in the hashtable by MHT_GROWTH_FACTOR and
- * rehash items.
- */
+/// Increase number of buckets in the hashtable by MHT_GROWTH_FACTOR and
+/// rehash items.
 static void mf_hash_grow(mf_hashtab_T *mht)
 {
   long_u i, j;
@@ -1182,16 +1085,14 @@ static void mf_hash_grow(mf_hashtab_T *mht)
     shift++;
 
   for (i = 0; i <= mht->mht_mask; i++) {
-    /*
-     * Traverse the items in the i-th original bucket and move them into
-     * MHT_GROWTH_FACTOR new buckets, preserving their relative order
-     * within each new bucket.  Preserving the order is important because
-     * mf_get() tries to keep most recently used items at the front of
-     * each bucket.
-     *
-     * Here we strongly rely on the fact the hashes are computed modulo
-     * a power of two.
-     */
+    /// Traverse the items in the i-th original bucket and move them into
+    /// MHT_GROWTH_FACTOR new buckets, preserving their relative order
+    /// within each new bucket. Preserving the order is important because
+    /// mf_get() tries to keep most recently used items at the front of
+    /// each bucket.
+    /// 
+    /// Here we strongly rely on the fact that hashes are computed modulo
+    /// a power of two.
 
     memset(tails, 0, sizeof(tails));
 
diff --git a/src/nvim/memfile.h b/src/nvim/memfile.h
index 3e71853326..085fa22f12 100644
--- a/src/nvim/memfile.h
+++ b/src/nvim/memfile.h
@@ -4,11 +4,11 @@
 #include "nvim/buffer_defs.h"
 #include "nvim/memfile_defs.h"
 
-/* flags for mf_sync() */
-#define MFS_ALL         1       /* also sync blocks with negative numbers */
-#define MFS_STOP        2       /* stop syncing when a character is available */
-#define MFS_FLUSH       4       /* flushed file to disk */
-#define MFS_ZERO        8       /* only write block 0 */
+/// flags for mf_sync()
+#define MFS_ALL         1       /// also sync blocks with negative numbers
+#define MFS_STOP        2       /// stop syncing when a character is available
+#define MFS_FLUSH       4       /// flushed file to disk
+#define MFS_ZERO        8       /// only write block 0
 
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "memfile.h.generated.h"
diff --git a/src/nvim/memfile_defs.h b/src/nvim/memfile_defs.h
index 2e6e914b57..5dc17a751a 100644
--- a/src/nvim/memfile_defs.h
+++ b/src/nvim/memfile_defs.h
@@ -4,15 +4,21 @@
 #include "nvim/types.h"
 
 typedef struct block_hdr bhdr_T;
-typedef long blocknr_T;
 
-/*
- * mf_hashtab_T is a chained hashtable with blocknr_T key and arbitrary
- * 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.
- */
+/// 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.
+///
+/// Items' keys are block numbers.
+/// Items in the same bucket are organized into a doubly-linked list.
+///
+/// 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
-                                     * in array is "mht_mask" + 1) */
-  long_u mht_count;                 /* nr of items inserted into hashtable */
-  mf_hashitem_T   **mht_buckets;    /* points to mht_small_buckets or
-                                     *dynamically allocated array */
-  mf_hashitem_T   *mht_small_buckets[MHT_INIT_SIZE];     /* initial buckets */
-  char mht_fixed;                   /* non-zero value forbids growth */
+  long_u mht_mask;              /// mask used to mod hash value to array index
+                                /// (nr of items in array is 'mht_mask + 1')
+  long_u mht_count;             /// number of items inserted
+  mf_hashitem_T **mht_buckets;  /// points to the array of buckets (can be
+                                /// mht_small_buckets or a newly allocated array
+                                /// when mht_small_buckets becomes too small)
+  mf_hashitem_T *mht_small_buckets[MHT_INIT_SIZE];     /// initial buckets
+  char mht_fixed;               /// non-zero value forbids growth
 } mf_hashtab_T;
 
-/*
- * for each (previously) used block in the memfile there is one block header.
- *
- * 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.
- *	mf_used_count is the number of pages in the used list.
- * The hash lists are used to quickly find a block in the used list.
- * The free list is a single linked list, not sorted.
- *	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.
- */
-
+/// A 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 used list is a doubly linked list, most recently used block first.
+/// The blocks in the used list have a block of memory allocated.
+/// mf_used_count is the number of pages in the used list.
+/// The hash lists are used to quickly find a block in the used list.
+/// The free list is a single linked list, not sorted.
+/// 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 */
-#define bh_bnum bh_hashitem.mhi_key /* block number, part of bh_hashitem */
+  mf_hashitem_T bh_hashitem;         /// header for hash table and key
+#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_prev;             /* previous block_hdr in used list */
-  char_u      *bh_data;             /* pointer to memory (for used block) */
-  int bh_page_count;                /* number of pages in this block */
+  bhdr_T *bh_next;                   /// next block_hdr in free or used list
+  bhdr_T *bh_prev;                   /// previous block_hdr in used list
+  char_u *bh_data;                   /// pointer to memory (for used 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
 };
 
-/*
- * 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
- * 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.
- */
+/// 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
+/// 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 */
-#define nt_old_bnum nt_hashitem.mhi_key /* old, negative, number */
-
-  blocknr_T nt_new_bnum;                /* new, positive, number */
+  mf_hashitem_T nt_hashitem;             /// header for hash table and key
+#define nt_old_bnum nt_hashitem.mhi_key  /// old, negative, 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_ffname;               /* idem, full path */
-  int mf_fd;                            /* file descriptor */
-  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_last;            /* lru block_hdr in used list */
-  unsigned mf_used_count;               /* number of pages in used list */
-  unsigned mf_used_count_max;           /* maximum number of pages in memory */
-  mf_hashtab_T mf_hash;                 /* hash lists */
-  mf_hashtab_T mf_trans;                /* trans lists */
-  blocknr_T mf_blocknr_max;             /* highest positive 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_infile_count;            /* number of pages in the file */
-  unsigned mf_page_size;                /* number of bytes in a page */
-  int mf_dirty;                         /* TRUE if there are dirty blocks */
+  char_u *mf_fname;                  /// name of the file
+  char_u *mf_ffname;                 /// idem, full path
+  int mf_fd;                         /// file descriptor
+  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_last;              /// lru block_hdr in used list
+  unsigned mf_used_count;            /// number of pages in used list
+  unsigned mf_used_count_max;        /// maximum number of pages in memory
+  mf_hashtab_T mf_hash;              /// hash lists
+  mf_hashtab_T mf_trans;             /// trans lists
+  blocknr_T mf_blocknr_max;          /// highest positive 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_infile_count;         /// number of pages in the file
+  unsigned mf_page_size;             /// number of bytes in a page
+  int mf_dirty;                      /// TRUE if there are dirty blocks
 };
 
 #endif // NVIM_MEMFILE_DEFS_H