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 siz