add descriptive comments to pretty much all functions and major

variables that don't have them, plus a few miscellaneous minor fixes


git-svn-id: svn://svn.savannah.gnu.org/nano/trunk/nano@3237 35c25a1d-7b9e-4130-9fde-d3aeb78583b8

ChangeLog

@@ -1,5 +1,7 @@
 CVS code -
 - General:
+	- Miscellaneous comment fixes. (DLR)
+	- More int -> bool conversions. (DLR)
 	- Add the ability to scroll up or down single lines without
 	  scrolling the cursor, via Meta-- and Meta-+.  Note that this
 	  is disabled when NANO_SMALL is defined.  New functions
@@ -170,6 +172,9 @@ CVS code -
 	  (DLR)
 - nano.h:
 	- Readd MIN_EDITOR_COLS #define, set to 4. (DLR)
+- proto.h:
+	- Remove now-unused externs for currslen, shortcut_list,
+	  fileinfo, syntaxfile_regexp, and synfilematches. (DLR)
 - prompt.c:
   do_statusbar_input()
 	- Fix misplaced break when handling NANO_VERBATIM_KEY. (DLR)
@@ -183,12 +188,17 @@ CVS code -
   do_rcfile()
 	- Remove unneeded assert. (DLR)
 - search.c:
+  search_abort()
+	- Rename to search_replace_abort(). (DLR)
   findnextstr()
 	- Remove parameter can_display_wrap, as it's always set to TRUE
 	  now, and rename parameter wholeword to whole_word, for
 	  consistency. (DLR)
 	- Only include the whole_word parameter when DISABLE_SPELLER
 	  isn't defined, as it's only used then. (DLR)
+  replace_abort()
+	- Replace with search_replace_abort(), since it does the same
+	  things that this function does. (DLR)
   do_replace_loop()
 	- Change order of parameters to more closely match those of
 	  findnextstr(), and rename parameter wholewords to whole_word,
@@ -244,6 +254,8 @@ CVS code -
 	- Fix test so that we scroll through the line in 8-character
 	  chunks when COLS is greater than 8, not when COLS is greater
 	  than 9. (DLR)
+  remove_magicline()
+	- Add assert. (DLR)
 - winio.c:
   nanoget_repaint()
 	- Rename parameter inputbuf to buf, for consistency. (DLR)

src/cut.c

@@ -31,6 +31,8 @@ static bool keep_cutbuffer = FALSE;
 static filestruct *cutbottom = NULL;
 	/* Pointer to the end of the cutbuffer. */
 
+/* Indicate that we should no longer keep the contents of the
+ * cutbuffer. */
 void cutbuffer_reset(void)
 {
     keep_cutbuffer = FALSE;

src/files.c

@@ -336,6 +336,8 @@ filestruct *read_line(char *buf, filestruct *prevnode, bool
     return fileptr;
 }
 
+/* Read an open file into the current buffer.  f should be set to the
+ * open file, and filename should be set to the name of the file. */
 void read_file(FILE *f, const char *filename)
 {
     size_t num_lines = 0;
@@ -665,6 +667,9 @@ char *get_next_filename(const char *name, const char *suffix)
     return buf;
 }
 
+/* Insert a file into a new buffer if the MULTIBUFFER flag is set, or
+ * into the current buffer if it isn't.  If execute is TRUE, insert the
+ * output of an executed command instead of a file. */
 void do_insertfile(
 #ifndef NANO_TINY
 	bool execute
@@ -871,6 +876,9 @@ void do_insertfile(
     free(ans);
 }
 
+/* Insert a file into a new buffer or the current buffer, depending on
+ * whether the MULTIBUFFER flag is set.  If we're in view mode, only
+ * allow inserting a file into a new buffer. */
 void do_insertfile_void(void)
 {
 #ifdef ENABLE_MULTIBUFFER
@@ -1687,6 +1695,10 @@ int write_marked_file(const char *name, FILE *f_open, bool tmp,
 }
 #endif /* !NANO_TINY */
 
+/* Write the current file to disk.  If the mark is on, write the current
+ * marked selection to disk.  If exiting is TRUE, write the file to disk
+ * regardless of whether the mark is on, and without prompting if the
+ * TEMP_FILE flag is set. */
 int do_writeout(bool exiting)
 {
     int i, retval = 0;
@@ -1854,6 +1866,8 @@ int do_writeout(bool exiting)
     return retval;
 }
 
+/* Write the current file to disk.  If the mark is on, write the current
+ * marked selection to disk. */
 void do_writeout_void(void)
 {
     do_writeout(FALSE);
@@ -2353,6 +2367,9 @@ void load_history(void)
     }
 }
 
+/* Write the lines of a history list, starting with the line at h, to
+ * the open file at hist.  Return TRUE if the write succeeded, and FALSE
+ * otherwise. */
 bool writehist(FILE *hist, filestruct *h)
 {
     filestruct *p;

src/global.c

@@ -25,132 +25,180 @@
 
 /* Global variables */
 #ifndef DISABLE_WRAPJUSTIFY
-ssize_t fill = 0;		/* The column where we will wrap
+ssize_t fill = 0;
-				 * lines. */
+	/* The column where we will wrap lines. */
 ssize_t wrap_at = -CHARS_FROM_EOL;
-				/* The position where we will wrap
+	/* The position where we will wrap lines.  fill is equal to this
-				 * lines.  fill is equal to this if it's
+	 * if it's greater than zero, and equal to (COLS + this) if it
-				 * greater than zero, and equal to
+	 * isn't. */
-				 * (COLS + this) if it isn't. */
 #endif
 
-char *last_search = NULL;	/* Last string we searched for */
+char *last_search = NULL;
-char *last_replace = NULL;	/* Last replacement string */
+	/* The last string we searched for. */
+char *last_replace = NULL;
+	/* The last replacement string we searched for. */
 
-long flags = 0;			/* Our flag containing many options */
+long flags = 0;
-WINDOW *topwin;			/* Top subwindow */
+	/* Our flag containing the states of all global options. */
-WINDOW *edit;			/* The file portion of the editor */
+WINDOW *topwin;
-WINDOW *bottomwin;		/* Bottom subwindow */
+	/* The top portion of the window, where we display the version
+	 * number of nano, the name of the current file, and whether the
+	 * current file has been modified. */
+WINDOW *edit;
+	/* The middle portion of the window, i.e, the edit window, where
+	 * we display the current file we're editing. */
+WINDOW *bottomwin;
+	/* The bottom portion of the window, where we display statusbar
+	 * messages, the statusbar prompt, and a list of shortcuts. */
+int editwinrows = 0;
+	/* How many rows does the edit window take up? */
 
-int editwinrows = 0;		/* How many rows long is the edit
+filestruct *cutbuffer = NULL;
-				   window? */
+	/* The buffer where we store cut text. */
-filestruct *cutbuffer = NULL;	/* A place to store cut text */
 #ifndef DISABLE_JUSTIFY
-filestruct *jusbuffer = NULL;	/* A place to store unjustified text */
+filestruct *jusbuffer = NULL;
+	/* The buffer where we store unjustified text. */
 #endif
-partition *filepart = NULL;	/* A place to store a portion of the
+partition *filepart = NULL;
-				   file struct */
+	/* The partition where we store a portion of the current
-
+	 * file. */
 openfilestruct *openfile = NULL;
-				/* The list of open file buffers */
+	/* The list of all open file buffers. */
 
 #if !defined(NANO_TINY) && defined(ENABLE_NANORC)
-char *whitespace = NULL;	/* Characters used when displaying
+char *whitespace = NULL;
-				   the first characters of tabs and
+	/* The characters used when displaying the first characters of
-				   spaces. */
+	 * tabs and spaces. */
-int whitespace_len[2];		/* The length of the characters. */
+int whitespace_len[2];
+	/* The length of these characters. */
 #endif
 
 #ifndef DISABLE_JUSTIFY
-char *punct = NULL;		/* Closing punctuation that can end
+char *punct = NULL;
-				   sentences. */
+	/* The closing punctuation that can end sentences. */
-char *brackets = NULL;		/* Closing brackets that can follow
+char *brackets = NULL;
-				   closing punctuation and can end
+	/* The closing brackets that can follow closing punctuation and
-				   sentences. */
+	 * can end sentences. */
-char *quotestr = NULL;		/* Quote string.  The default value is
+char *quotestr = NULL;
-				   set in main(). */
+	/* The quoting string.  The default value is set in main(). */
 #ifdef HAVE_REGEX_H
-regex_t quotereg;		/* Compiled quotestr regular expression. */
+regex_t quotereg;
-int quoterc;			/* Did it compile? */
+	/* The compiled regular expression from the quoting string. */
-char *quoteerr = NULL;		/* The error message. */
+int quoterc;
+	/* Whether it actually compiled. */
+char *quoteerr = NULL;
+	/* The error message, if it didn't. */
 #else
-size_t quotelen;		/* strlen(quotestr) */
+size_t quotelen;
+	/* The length of the quoting string in bytes. */
 #endif
 #endif
 
+char *answer = NULL;
+	/* The answer string used in the statusbar prompt. */
+
+ssize_t tabsize = -1;
+	/* The width of a tab in spaces.  The default value is set in
+	 * main(). */
+
 #ifndef NANO_TINY
-char *backup_dir = NULL;	/* Backup directory. */
+char *backup_dir = NULL;
+	/* The directory where we store backup files. */
 #endif
-
-char *answer = NULL;		/* The answer string for statusbar
-				 * questions. */
-
-ssize_t tabsize = -1;		/* Our internal tabsize variable.  The
-				   default value is set in main(). */
-
 #ifndef DISABLE_OPERATINGDIR
-char *operating_dir = NULL;	/* Operating directory, which we can't */
+char *operating_dir = NULL;
-char *full_operating_dir = NULL;/* go higher than */
+	/* The relative path to the operating directory, which we can't
+	 * move outside of. */
+char *full_operating_dir = NULL;
+	/* The full path to it. */
 #endif
 
 #ifndef DISABLE_SPELLER
-char *alt_speller = NULL;		/* Alternative spell command */
+char *alt_speller = NULL;
+	/* The command to use for the alternate spell checker. */
 #endif
 
 shortcut *main_list = NULL;
+	/* The main shortcut list. */
 shortcut *whereis_list = NULL;
+	/* The "Search" shortcut list. */
 shortcut *replace_list = NULL;
-shortcut *replace_list_2 = NULL; 	/* 2nd half of replace dialog */
+	/* The "Search (to replace)" shortcut list. */
+shortcut *replace_list_2 = NULL;
+	/* The "Replace with" shortcut list. */
 shortcut *gotoline_list = NULL;
+	/* The "Enter line number, column number" shortcut list. */
 shortcut *writefile_list = NULL;
+	/* The "File Name to Write" shortcut list. */
 shortcut *insertfile_list = NULL;
+	/* The "File to insert" shortcut list. */
+#ifndef NANO_TINY
+shortcut *extcmd_list = NULL;
+	/* The "Command to execute" shortcut list. */
+#endif
 #ifndef DISABLE_HELP
 shortcut *help_list = NULL;
+	/* The help text shortcut list. */
 #endif
 #ifndef DISABLE_SPELLER
 shortcut *spell_list = NULL;
-#endif
+	/* The internal spell checker shortcut list. */
-#ifndef NANO_TINY
-shortcut *extcmd_list = NULL;
 #endif
 #ifndef DISABLE_BROWSER
 shortcut *browser_list = NULL;
+	/* The file browser shortcut list. */
 shortcut *gotodir_list = NULL;
+	/* The "Go To Directory" shortcut list. */
 #endif
 
 #ifdef ENABLE_COLOR
 syntaxtype *syntaxes = NULL;
+	/* The global list of color syntaxes. */
 char *syntaxstr = NULL;
+	/* The color syntax name specified on the command line. */
 #endif
 
-const shortcut *currshortcut;	/* Current shortcut list we're using */
+const shortcut *currshortcut;
-
+	/* The current shortcut list we're using. */
 #ifndef NANO_TINY
 toggle *toggles = NULL;
+	/* The global toggle list. */
 #endif
 
 #ifndef NANO_TINY
 filestruct *search_history = NULL;
+	/* The search string history list. */
 filestruct *searchage = NULL;
+	/* The top of the search string history list. */
 filestruct *searchbot = NULL;
+	/* The bottom of the search string history list. */
 filestruct *replace_history = NULL;
+	/* The replace string history list. */
 filestruct *replaceage = NULL;
+	/* The top of the replace string history list. */
 filestruct *replacebot = NULL;
+	/* The bottom of the replace string history list. */
 #endif
 
 /* Regular expressions */
 #ifdef HAVE_REGEX_H
-regex_t search_regexp;		/* Global to store compiled search regexp */
+regex_t search_regexp;
-regmatch_t regmatches[10];	/* Match positions for parenthetical
+	/* The compiled regular expression to use in searches. */
-				   subexpressions, max of 10 */
+regmatch_t regmatches[10];
+	/* The match positions for parenthetical subexpressions, 10
+	 * maximum, used in regular expression searches. */
 #endif
 
-bool curses_ended = FALSE;	/* Indicates to statusbar() to simply
+bool curses_ended = FALSE;
-				 * write to stderr, since endwin() has
+	/* Whether endwin() has ended curses mode and statusbar()
-				 * ended curses mode. */
+	 * should hence write to stderr instead of displaying on the
+	 * statusbar. */
 
-char *homedir = NULL;		/* $HOME or from /etc/passwd. */
+char *homedir = NULL;
+		/* The user's home directory, from $HOME or
+		 * /etc/passwd. */
 
+/* Return the number of entries in the shortcut list s. */
 size_t length_of_list(const shortcut *s)
 {
     size_t i = 0;
@@ -194,6 +242,8 @@ void sc_init_one(shortcut **shortcutage, int ctrlval, const char *desc,
     s->next = NULL;
 }
 
+/* Initialize all shortcut lists.  If unjustify is TRUE, replace the
+ * Uncut shortcut in the main shortcut list with UnJustify. */
 void shortcut_init(bool unjustify)
 {
     const char *get_help_msg = N_("Get Help");
@@ -365,7 +415,7 @@ void shortcut_init(bool unjustify)
 
     free_shortcutage(&main_list);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_HELP_KEY, get_help_msg,
 	IFHELP(nano_help_msg, NANO_NO_KEY), NANO_HELP_FKEY,
 	NANO_NO_KEY, VIEW,
@@ -376,7 +426,7 @@ void shortcut_init(bool unjustify)
 #endif
 		);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_EXIT_KEY,
 #ifdef ENABLE_MULTIBUFFER
 	openfile != NULL && openfile != openfile->next ?
@@ -385,12 +435,12 @@ void shortcut_init(bool unjustify)
 	exit_msg, IFHELP(nano_exit_msg, NANO_NO_KEY), NANO_EXIT_FKEY,
 	NANO_NO_KEY, VIEW, do_exit);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_WRITEOUT_KEY, N_("WriteOut"),
 	IFHELP(nano_writeout_msg, NANO_NO_KEY), NANO_WRITEOUT_FKEY,
 	NANO_NO_KEY, NOVIEW, do_writeout_void);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_JUSTIFY_KEY, N_("Justify"),
 	IFHELP(nano_justify_msg, NANO_NO_KEY),
 	NANO_JUSTIFY_FKEY, NANO_NO_KEY, NOVIEW,
@@ -402,11 +452,12 @@ void shortcut_init(bool unjustify)
 		);
 
     /* We allow inserting files in view mode if multibuffers are
-     * available, so that we can view multiple files. */
+     * available, so that we can view multiple files.  If we're using
-    /* If we're using restricted mode, inserting files is disabled since
+     * restricted mode, inserting files is disabled, since it allows
-     * it allows reading from or writing to files not specified on the
+     * reading from or writing to files not specified on the command
-     * command line. */
+     * line. */
-    /* Translators: try to keep this string under 10 characters long */
+
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_INSERTFILE_KEY, N_("Read File"),
 	IFHELP(nano_insert_msg, NANO_NO_KEY), NANO_INSERTFILE_FKEY,
 	NANO_NO_KEY,
@@ -418,38 +469,38 @@ void shortcut_init(bool unjustify)
 		, !ISSET(RESTRICTED) ? do_insertfile_void :
 		nano_disabled_msg);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_WHEREIS_KEY, N_("Where Is"),
 	IFHELP(nano_whereis_msg, NANO_NO_KEY), NANO_WHEREIS_FKEY,
 	NANO_NO_KEY, VIEW, do_search);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_PREVPAGE_KEY, prev_page_msg,
 	IFHELP(nano_prevpage_msg, NANO_NO_KEY), NANO_PREVPAGE_FKEY,
 	NANO_NO_KEY, VIEW, do_page_up);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_NEXTPAGE_KEY, next_page_msg,
 	IFHELP(nano_nextpage_msg, NANO_NO_KEY), NANO_NEXTPAGE_FKEY,
 	NANO_NO_KEY, VIEW, do_page_down);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_CUT_KEY, N_("Cut Text"),
 	IFHELP(nano_cut_msg, NANO_NO_KEY), NANO_CUT_FKEY,
 	NANO_NO_KEY, NOVIEW, do_cut_text);
 
     if (unjustify)
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
 	sc_init_one(&main_list, NANO_UNJUSTIFY_KEY, N_("UnJustify"),
 		IFHELP(NULL, NANO_NO_KEY), NANO_UNJUSTIFY_FKEY,
 		NANO_NO_KEY, NOVIEW, NULL);
     else
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
 	sc_init_one(&main_list, NANO_UNCUT_KEY, N_("UnCut Txt"),
 		IFHELP(nano_uncut_msg, NANO_NO_KEY), NANO_UNCUT_FKEY,
 		NANO_NO_KEY, NOVIEW, do_uncut_text);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_CURSORPOS_KEY, N_("Cur Pos"),
 	IFHELP(nano_cursorpos_msg, NANO_NO_KEY), NANO_CURSORPOS_FKEY,
 	NANO_NO_KEY, VIEW, do_cursorpos_void);
@@ -457,7 +508,7 @@ void shortcut_init(bool unjustify)
     /* If we're using restricted mode, spell checking is disabled
      * because it allows reading from or writing to files not specified
      * on the command line. */
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_SPELL_KEY, N_("To Spell"),
 		IFHELP(nano_spell_msg, NANO_NO_KEY), NANO_SPELL_FKEY,
 		NANO_NO_KEY, NOVIEW,
@@ -552,12 +603,12 @@ void shortcut_init(bool unjustify)
 #endif
 
 #ifndef DISABLE_JUSTIFY
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_NO_KEY, beg_of_par_msg,
 	IFHELP(nano_parabegin_msg, NANO_PARABEGIN_ALTKEY1), NANO_NO_KEY,
 	NANO_PARABEGIN_ALTKEY2, VIEW, do_para_begin_void);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_NO_KEY, end_of_par_msg,
 	IFHELP(nano_paraend_msg, NANO_PARAEND_ALTKEY1), NANO_NO_KEY,
 	NANO_PARAEND_ALTKEY2, VIEW, do_para_end_void);
@@ -578,14 +629,14 @@ void shortcut_init(bool unjustify)
 	NANO_NO_KEY, NOVIEW, do_verbatim_input);
 
 #ifndef NANO_TINY
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_NO_KEY, cut_till_end_msg,
 	IFHELP(nano_cut_till_end_msg, NANO_CUTTILLEND_ALTKEY),
 	NANO_NO_KEY, NANO_NO_KEY, NOVIEW, do_cut_till_end);
 #endif
 
 #ifndef DISABLE_JUSTIFY
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&main_list, NANO_NO_KEY, fulljstify_msg,
 	IFHELP(nano_fulljustify_msg, NANO_FULLJUSTIFY_ALTKEY),
 	NANO_NO_KEY, NANO_NO_KEY, NOVIEW, do_full_justify);
@@ -609,76 +660,76 @@ void shortcut_init(bool unjustify)
 #endif
 		);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_CANCEL_KEY, cancel_msg,
 	IFHELP(nano_cancel_msg, NANO_NO_KEY), NANO_NO_KEY,
 	NANO_NO_KEY, VIEW, NULL);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_FIRSTLINE_KEY, first_line_msg,
 	IFHELP(nano_firstline_msg, NANO_NO_KEY), NANO_FIRSTLINE_FKEY,
 	NANO_NO_KEY, VIEW, do_first_line);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_LASTLINE_KEY, last_line_msg,
 	IFHELP(nano_lastline_msg, NANO_NO_KEY), NANO_LASTLINE_FKEY,
 	NANO_NO_KEY, VIEW, do_last_line);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_TOOTHERSEARCH_KEY, replace_msg,
 	IFHELP(nano_replace_msg, NANO_NO_KEY), NANO_REPLACE_FKEY,
 	NANO_NO_KEY, VIEW, NULL);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_TOGOTOLINE_KEY, go_to_line_msg,
 	IFHELP(nano_gotoline_msg, NANO_NO_KEY), NANO_GOTOLINE_FKEY,
 	NANO_NO_KEY, VIEW, NULL);
 
 #ifndef DISABLE_JUSTIFY
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_PARABEGIN_KEY, beg_of_par_msg,
 	IFHELP(nano_parabegin_msg, NANO_PARABEGIN_ALTKEY1), NANO_NO_KEY,
 	NANO_PARABEGIN_ALTKEY2, VIEW, do_para_begin_void);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_PARAEND_KEY, end_of_par_msg,
 	IFHELP(nano_paraend_msg, NANO_PARAEND_ALTKEY1), NANO_NO_KEY,
 	NANO_PARAEND_ALTKEY2, VIEW, do_para_end_void);
 #endif
 
 #ifndef NANO_TINY
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_NO_KEY, case_sens_msg,
 	IFHELP(nano_case_msg, TOGGLE_CASE_KEY), NANO_NO_KEY,
 	NANO_NO_KEY, VIEW, NULL);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_NO_KEY, backwards_msg,
 	IFHELP(nano_reverse_msg, TOGGLE_BACKWARDS_KEY), NANO_NO_KEY,
 	NANO_NO_KEY, VIEW, NULL);
 #endif
 
 #ifdef HAVE_REGEX_H
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_NO_KEY, regexp_msg,
 	IFHELP(nano_regexp_msg, NANO_REGEXP_KEY), NANO_NO_KEY,
 	NANO_NO_KEY, VIEW, NULL);
 #endif
 
 #ifndef NANO_TINY
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_PREVLINE_KEY, history_msg,
 	IFHELP(nano_history_msg, NANO_NO_KEY), NANO_NO_KEY,
 	NANO_NO_KEY, VIEW, NULL);
 
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_CUTTILLEND_KEY, cut_till_end_msg,
 	IFHELP(nano_cut_till_end_msg, NANO_CUTTILLEND_ALTKEY),
 	NANO_NO_KEY, NANO_NO_KEY, NOVIEW, do_cut_till_end);
 #endif
 
 #ifndef DISABLE_JUSTIFY
-    /* Translators: try to keep this string under 10 characters long */
+    /* Translators: try to keep this string under 10 characters long. */
     sc_init_one(&whereis_list, NANO_FULLJUSTIFY_KEY, fulljstify_msg,
 	IFHELP(nano_fulljustify_msg, NANO_FULLJUSTIFY_ALTKEY),
 	NANO_NO_KEY, NANO_NO_KEY, NOVIEW, do_full_justify);
@@ -708,7 +759,7 @@ void shortcut_init(bool unjustify)
 	IFHELP(nano_lastline_msg, NANO_NO_KEY), NANO_LASTLINE_FKEY,
 	NANO_NO_KEY, VIEW, do_last_line);
 
-    /* Translators: try to keep this string under 12 characters long */
+    /* Translators: try to keep this string under 12 characters long. */
     sc_init_one(&replace_list, NANO_TOOTHERSEARCH_KEY, N_("No Replace"),
 	IFHELP(nano_whereis_msg, NANO_NO_KEY), NANO_REPLACE_FKEY,
 	NANO_NO_KEY, VIEW, NULL);
@@ -797,34 +848,6 @@ void shortcut_init(bool unjustify)
 	N_("Go To Text"), IFHELP(nano_whereis_msg, NANO_NO_KEY),
 	NANO_NO_KEY, NANO_NO_KEY, VIEW, NULL);
 
-#ifndef DISABLE_HELP
-    free_shortcutage(&help_list);
-
-    sc_init_one(&help_list, NANO_REFRESH_KEY, refresh_msg,
-	IFHELP(nano_refresh_msg, NANO_NO_KEY), NANO_NO_KEY,
-	NANO_NO_KEY, VIEW, NULL);
-
-    sc_init_one(&help_list, NANO_EXIT_KEY, exit_msg,
-	IFHELP(nano_exit_msg, NANO_NO_KEY), NANO_EXIT_FKEY,
-	NANO_NO_KEY, VIEW, NULL);
-
-    sc_init_one(&help_list, NANO_PREVPAGE_KEY, prev_page_msg,
-	IFHELP(nano_prevpage_msg, NANO_NO_KEY), NANO_PREVPAGE_FKEY,
-	NANO_NO_KEY, VIEW, NULL);
-
-    sc_init_one(&help_list, NANO_NEXTPAGE_KEY, next_page_msg,
-	IFHELP(nano_nextpage_msg, NANO_NO_KEY), NANO_NEXTPAGE_FKEY,
-	NANO_NO_KEY, VIEW, NULL);
-
-    sc_init_one(&help_list, NANO_PREVLINE_KEY, N_("Prev Line"),
-	IFHELP(nano_prevline_msg, NANO_NO_KEY), NANO_NO_KEY,
-	NANO_NO_KEY, VIEW, NULL);
-
-    sc_init_one(&help_list, NANO_NEXTLINE_KEY, N_("Next Line"),
-	IFHELP(nano_nextline_msg, NANO_NO_KEY), NANO_NO_KEY,
-	NANO_NO_KEY, VIEW, NULL);
-#endif
-
     free_shortcutage(&writefile_list);
 
     sc_init_one(&writefile_list, NANO_HELP_KEY, get_help_msg,
@@ -844,7 +867,8 @@ void shortcut_init(bool unjustify)
 #ifndef DISABLE_BROWSER
     /* If we're using restricted mode, the file browser is disabled.
      * It's useless since inserting files is disabled. */
-    /* Translators: try to keep this string under 16 characters long */
+
+    /* Translators: try to keep this string under 16 characters long. */
     if (!ISSET(RESTRICTED))
 	sc_init_one(&writefile_list, NANO_TOFILES_KEY, to_files_msg,
 		IFHELP(nano_tofiles_msg, NANO_NO_KEY), NANO_NO_KEY,
@@ -858,33 +882,34 @@ void shortcut_init(bool unjustify)
      * and fourth are disabled because they allow writing to files not
      * specified on the command line, and the fifth is useless since
      * backups are disabled. */
-    /* Translators: try to keep this string under 16 characters long */
+
+    /* Translators: try to keep this string under 16 characters long. */
     if (!ISSET(RESTRICTED))
 	sc_init_one(&writefile_list, NANO_NO_KEY, N_("DOS Format"),
 		IFHELP(nano_dos_msg, TOGGLE_DOS_KEY), NANO_NO_KEY,
 		NANO_NO_KEY, NOVIEW, NULL);
 
-    /* Translators: try to keep this string under 16 characters long */
+    /* Translators: try to keep this string under 16 characters long. */
     if (!ISSET(RESTRICTED))
 	sc_init_one(&writefile_list, NANO_NO_KEY, N_("Mac Format"),
 		IFHELP(nano_mac_msg, TOGGLE_MAC_KEY), NANO_NO_KEY,
 		NANO_NO_KEY, NOVIEW, NULL);
 #endif
 
-    /* Translators: try to keep this string under 16 characters long */
+    /* Translators: try to keep this string under 16 characters long. */
     if (!ISSET(RESTRICTED))
 	sc_init_one(&writefile_list, NANO_NO_KEY, N_("Append"),
 		IFHELP(nano_append_msg, NANO_APPEND_KEY), NANO_NO_KEY,
 		NANO_NO_KEY, NOVIEW, NULL);
 
-    /* Translators: try to keep this string under 16 characters long */
+    /* Translators: try to keep this string under 16 characters long. */
     if (!ISSET(RESTRICTED))
 	sc_init_one(&writefile_list, NANO_NO_KEY, N_("Prepend"),
 		IFHELP(nano_prepend_msg, NANO_PREPEND_KEY), NANO_NO_KEY,
 		NANO_NO_KEY, NOVIEW, NULL);
 
 #ifndef NANO_TINY
-    /* Translators: try to keep this string under 16 characters long */
+    /* Translators: try to keep this string under 16 characters long. */
     if (!ISSET(RESTRICTED))
 	sc_init_one(&writefile_list, NANO_NO_KEY, N_("Backup File"),
 		IFHELP(nano_backup_msg, TOGGLE_BACKUP_KEY), NANO_NO_KEY,
@@ -919,7 +944,8 @@ void shortcut_init(bool unjustify)
 #ifndef NANO_TINY
     /* If we're using restricted mode, command execution is disabled.
      * It's useless since inserting files is disabled. */
-    /* Translators: try to keep this string under 22 characters long */
+
+    /* Translators: try to keep this string under 22 characters long. */
     if (!ISSET(RESTRICTED))
 	sc_init_one(&insertfile_list, NANO_TOOTHERINSERT_KEY,
 		N_("Execute Command"), IFHELP(nano_execute_msg,
@@ -928,7 +954,8 @@ void shortcut_init(bool unjustify)
 #ifdef ENABLE_MULTIBUFFER
     /* If we're using restricted mode, the multibuffer toggle is
      * disabled.  It's useless since inserting files is disabled. */
-    /* Translators: try to keep this string under 22 characters long */
+
+    /* Translators: try to keep this string under 22 characters long. */
     if (!ISSET(RESTRICTED))
 	sc_init_one(&insertfile_list, NANO_NO_KEY, new_buffer_msg,
 		IFHELP(nano_multibuffer_msg, TOGGLE_MULTIBUFFER_KEY),
@@ -936,24 +963,6 @@ void shortcut_init(bool unjustify)
 #endif
 #endif
 
-#ifndef DISABLE_SPELLER
-    free_shortcutage(&spell_list);
-
-    sc_init_one(&spell_list, NANO_HELP_KEY, get_help_msg,
-	IFHELP(nano_help_msg, NANO_NO_KEY), NANO_HELP_FKEY,
-	NANO_NO_KEY, VIEW,
-#ifndef DISABLE_HELP
-		do_help
-#else
-		nano_disabled_msg
-#endif
-		);
-
-    sc_init_one(&spell_list, NANO_CANCEL_KEY, cancel_msg,
-	IFHELP(nano_cancel_msg, NANO_NO_KEY), NANO_NO_KEY,
-	NANO_NO_KEY, VIEW, NULL);
-#endif
-
 #ifndef NANO_TINY
     free_shortcutage(&extcmd_list);
 
@@ -982,6 +991,52 @@ void shortcut_init(bool unjustify)
 #endif
 #endif
 
+#ifndef DISABLE_HELP
+    free_shortcutage(&help_list);
+
+    sc_init_one(&help_list, NANO_REFRESH_KEY, refresh_msg,
+	IFHELP(nano_refresh_msg, NANO_NO_KEY), NANO_NO_KEY,
+	NANO_NO_KEY, VIEW, NULL);
+
+    sc_init_one(&help_list, NANO_EXIT_KEY, exit_msg,
+	IFHELP(nano_exit_msg, NANO_NO_KEY), NANO_EXIT_FKEY,
+	NANO_NO_KEY, VIEW, NULL);
+
+    sc_init_one(&help_list, NANO_PREVPAGE_KEY, prev_page_msg,
+	IFHELP(nano_prevpage_msg, NANO_NO_KEY), NANO_PREVPAGE_FKEY,
+	NANO_NO_KEY, VIEW, NULL);
+
+    sc_init_one(&help_list, NANO_NEXTPAGE_KEY, next_page_msg,
+	IFHELP(nano_nextpage_msg, NANO_NO_KEY), NANO_NEXTPAGE_FKEY,
+	NANO_NO_KEY, VIEW, NULL);
+
+    sc_init_one(&help_list, NANO_PREVLINE_KEY, N_("Prev Line"),
+	IFHELP(nano_prevline_msg, NANO_NO_KEY), NANO_NO_KEY,
+	NANO_NO_KEY, VIEW, NULL);
+
+    sc_init_one(&help_list, NANO_NEXTLINE_KEY, N_("Next Line"),
+	IFHELP(nano_nextline_msg, NANO_NO_KEY), NANO_NO_KEY,
+	NANO_NO_KEY, VIEW, NULL);
+#endif
+
+#ifndef DISABLE_SPELLER
+    free_shortcutage(&spell_list);
+
+    sc_init_one(&spell_list, NANO_HELP_KEY, get_help_msg,
+	IFHELP(nano_help_msg, NANO_NO_KEY), NANO_HELP_FKEY,
+	NANO_NO_KEY, VIEW,
+#ifndef DISABLE_HELP
+		do_help
+#else
+		nano_disabled_msg
+#endif
+		);
+
+    sc_init_one(&spell_list, NANO_CANCEL_KEY, cancel_msg,
+	IFHELP(nano_cancel_msg, NANO_NO_KEY), NANO_NO_KEY,
+	NANO_NO_KEY, VIEW, NULL);
+#endif
+
 #ifndef DISABLE_BROWSER
     free_shortcutage(&browser_list);
 
@@ -1007,7 +1062,7 @@ void shortcut_init(bool unjustify)
 	IFHELP(nano_nextpage_msg, NANO_NO_KEY), NANO_NEXTPAGE_FKEY,
 	NANO_NO_KEY, VIEW, NULL);
 
-    /* Translators: try to keep this string under 22 characters long */
+    /* Translators: try to keep this string under 22 characters long. */
     sc_init_one(&browser_list, NANO_GOTOLINE_KEY, N_("Go To Dir"),
 	IFHELP(nano_gotodir_msg, NANO_GOTOLINE_ALTKEY),
 	NANO_GOTOLINE_FKEY, NANO_NO_KEY, VIEW, NULL);
@@ -1071,6 +1126,7 @@ void toggle_init_one(int val, const char *desc, long flag)
     u->next = NULL;
 }
 
+/* Initialize the global toggle list. */
 void toggle_init(void)
 {
     /* There is no need to reinitialize the toggles.  They can't
@@ -1185,15 +1241,15 @@ void thanks_for_all_the_fish(void)
     free_shortcutage(&gotoline_list);
     free_shortcutage(&writefile_list);
     free_shortcutage(&insertfile_list);
+#ifndef NANO_TINY
+    free_shortcutage(&extcmd_list);
+#endif
 #ifndef DISABLE_HELP
     free_shortcutage(&help_list);
 #endif
 #ifndef DISABLE_SPELLER
     free_shortcutage(&spell_list);
 #endif
-#ifndef NANO_TINY
-    free_shortcutage(&extcmd_list);
-#endif
 #ifndef DISABLE_BROWSER
     free_shortcutage(&browser_list);
     free_shortcutage(&gotodir_list);

src/move.c

@@ -26,6 +26,7 @@
 #include <string.h>
 #include <ctype.h>
 
+/* Move to the first line of the file. */
 void do_first_line(void)
 {
     const filestruct *current_save = openfile->current;
@@ -40,6 +41,7 @@ void do_first_line(void)
     edit_redraw(current_save, pww_save);
 }
 
+/* Move to the last line of the file. */
 void do_last_line(void)
 {
     const filestruct *current_save = openfile->current;
@@ -55,6 +57,7 @@ void do_last_line(void)
     edit_redraw(current_save, pww_save);
 }
 
+/* Move up one page. */
 void do_page_up(void)
 {
     int i;
@@ -95,6 +98,7 @@ void do_page_up(void)
     edit_scroll(UP, editwinrows - 2);
 }
 
+/* Move down one page. */
 void do_page_down(void)
 {
     int i;
@@ -138,7 +142,8 @@ void do_page_down(void)
 
 #ifndef DISABLE_JUSTIFY
 /* Move up to the beginning of the last beginning-of-paragraph line
- * before the current line. */
+ * before the current line.  If allow_update is TRUE, update the screen
+ * afterwards. */
 void do_para_begin(bool allow_update)
 {
     const filestruct *current_save = openfile->current;
@@ -160,6 +165,8 @@ void do_para_begin(bool allow_update)
 	edit_redraw(current_save, pww_save);
 }
 
+/* Move up to the beginning of the last beginning-of-paragraph line
+ * before the current line, and update the screen afterwards. */
 void do_para_begin_void(void)
 {
     do_para_begin(TRUE);
@@ -167,9 +174,10 @@ void do_para_begin_void(void)
 
 /* Move down to the beginning of the last line of the current paragraph.
  * Then move down one line farther if there is such a line, or to the
- * end of the current line if not.  A line is the last line of a
+ * end of the current line if not.  If allow_update is TRUE, update the
- * paragraph if it is in a paragraph, and the next line either is a
+ * screen afterwards.  A line is the last line of a paragraph if it is
- * beginning-of-paragraph line or isn't in a paragraph. */
+ * in a paragraph, and the next line either is the beginning line of a
+ * paragraph or isn't in a paragraph. */
 void do_para_end(bool allow_update)
 {
     const filestruct *const current_save = openfile->current;
@@ -201,6 +209,9 @@ void do_para_end(bool allow_update)
 	edit_redraw(current_save, pww_save);
 }
 
+/* Move down to the beginning of the last line of the current paragraph.
+ * Then move down one line farther if there is such a line, or to the
+ * end of the current line if not, and update the screen afterwards. */
 void do_para_end_void(void)
 {
     do_para_end(TRUE);
@@ -208,10 +219,10 @@ void do_para_end_void(void)
 #endif /* !DISABLE_JUSTIFY */
 
 #ifndef NANO_TINY
-/* Move to the next word in the current filestruct.  If allow_punct is
+/* Move to the next word in the file.  If allow_punct is TRUE, treat
- * TRUE, treat punctuation as part of a word.  If allow_update is TRUE,
+ * punctuation as part of a word.  If allow_update is TRUE, update the
- * update the screen afterward.  Return TRUE if we started on a word,
+ * screen afterwards.  Return TRUE if we started on a word, and FALSE
- * and FALSE otherwise. */
+ * otherwise. */
 bool do_next_word(bool allow_punct, bool allow_update)
 {
     size_t pww_save = openfile->placewewant;
@@ -298,15 +309,18 @@ bool do_next_word(bool allow_punct, bool allow_update)
     return started_on_word;
 }
 
+/* Move to the next word in the file, treating punctuation as part of a
+ * word if the WORD_BOUNDS flag is set, and update the screen
+ * afterwards. */
 void do_next_word_void(void)
 {
     do_next_word(ISSET(WORD_BOUNDS), TRUE);
 }
 
-/* Move to the previous word in the current filestruct.  If allow_punct
+/* Move to the previous word in the file.  If allow_punct is TRUE, treat
- * is TRUE, treat punctuation as part of a word.  If allow_update is
+ * punctuation as part of a word.  If allow_update is TRUE, update the
- * TRUE, update the screen afterward.  Return TRUE if we started on a
+ * screen afterwards.  Return TRUE if we started on a word, and FALSE
- * word, and FALSE otherwise. */
+ * otherwise. */
 bool do_prev_word(bool allow_punct, bool allow_update)
 {
     size_t pww_save = openfile->placewewant;
@@ -429,12 +443,19 @@ bool do_prev_word(bool allow_punct, bool allow_update)
     return started_on_word;
 }
 
+/* Move to the previous word in the file, treating punctuation as part
+ * of a word if the WORD_BOUNDS flag is set, and update the screen
+ * afterwards. */
 void do_prev_word_void(void)
 {
     do_prev_word(ISSET(WORD_BOUNDS), TRUE);
 }
 #endif /* !NANO_TINY */
 
+/* Move to the beginning of the current line.  If the SMART_HOME flag is
+ * set, move to the first non-whitespace character of the current line
+ * if we're not already there, or to the beginning of the current line
+ * if we are. */
 void do_home(void)
 {
     size_t pww_save = openfile->placewewant;
@@ -464,6 +485,7 @@ void do_home(void)
 	update_line(openfile->current, openfile->current_x);
 }
 
+/* Move to the end of the current line. */
 void do_end(void)
 {
     size_t pww_save = openfile->placewewant;
@@ -477,6 +499,7 @@ void do_end(void)
 	update_line(openfile->current, openfile->current_x);
 }
 
+/* Move up one line. */
 void do_up(void)
 {
     check_statusblank();
@@ -516,6 +539,7 @@ void do_up(void)
 }
 
 #ifndef NANO_TINY
+/* Scroll up one line without scrolling the cursor. */
 void do_scroll_up(void)
 {
     check_statusblank();
@@ -540,6 +564,7 @@ void do_scroll_up(void)
 }
 #endif /* !NANO_TINY */
 
+/* Move down one line. */
 void do_down(void)
 {
     check_statusblank();
@@ -579,6 +604,7 @@ void do_down(void)
 }
 
 #ifndef NANO_TINY
+/* Scroll down one line without scrolling the cursor. */
 void do_scroll_down(void)
 {
     check_statusblank();
@@ -603,6 +629,7 @@ void do_scroll_down(void)
 }
 #endif /* !NANO_TINY */
 
+/* Move left one character. */
 void do_left(void)
 {
     size_t pww_save = openfile->placewewant;
@@ -623,6 +650,7 @@ void do_left(void)
 	update_line(openfile->current, openfile->current_x);
 }
 
+/* Move right one character. */
 void do_right(void)
 {
     size_t pww_save = openfile->placewewant;

src/nano.c

@@ -47,12 +47,14 @@
 #include <setjmp.h>
 #endif
 
-static struct termios oldterm;	/* The user's original term settings. */
+static struct termios oldterm;
-static struct sigaction act;	/* For all our fun signal handlers. */
+	/* The user's original terminal settings. */
+static struct sigaction act;
+	/* For all our fun signal handlers. */
 
 #ifndef NANO_TINY
-static sigjmp_buf jmpbuf;	/* Used to return to main() after a
+static sigjmp_buf jmpbuf;
-				 * SIGWINCH. */
+	/* Used to return to main() after a SIGWINCH. */
 #endif
 
 /* Create a new filestruct node.  Note that we specifically do not set
@@ -523,6 +525,7 @@ void free_openfilestruct(openfilestruct *src)
 }
 #endif
 
+/* Display a warning about a key disabled in view mode. */
 void print_view_warning(void)
 {
     statusbar(_("Key illegal in VIEW mode"));
@@ -597,6 +600,8 @@ void die(const char *msg, ...)
     exit(1);
 }
 
+/* Save the current file under the name spacified in die_filename, which
+ * is modified to be unique if necessary. */
 void die_save_file(const char *die_filename)
 {
     char *retval;
@@ -630,6 +635,7 @@ void die_save_file(const char *die_filename)
     free(retval);
 }
 
+/* Initialize the three window portions nano uses. */
 void window_init(void)
 {
     /* If the screen height is too small, get out. */
@@ -668,6 +674,7 @@ void window_init(void)
 }
 
 #ifndef DISABLE_MOUSE
+/* Initialize mouse support. */
 void mouse_init(void)
 {
     if (ISSET(USE_MOUSE)) {
@@ -710,6 +717,7 @@ void print1opt_full(const char *shortflag
     printf("\n");
 }
 
+/* Explain how to properly use nano and its command line options. */
 void usage(void)
 {
 #ifdef HAVE_GETOPT_LONG
@@ -818,6 +826,9 @@ void usage(void)
     exit(0);
 }
 
+/* Display the current version of nano, the date and time it was
+ * compiled, contact information for it, and the configuration options
+ * it was compiled with. */
 void version(void)
 {
     printf(_(" GNU nano version %s (compiled %s, %s)\n"), VERSION,
@@ -883,16 +894,23 @@ void version(void)
     printf("\n");
 }
 
+/* Return 1 if the MORE_SPACE flag is set, and 0 otherwise.  This is
+ * used to calculate the relative screen position while taking this flag
+ * into account, since it adds one line to the edit window. */
 int no_more_space(void)
 {
     return ISSET(MORE_SPACE) ? 1 : 0;
 }
 
+/* Return 2 if the NO_HELP flag is set, and 0 otherwise.  This is used
+ * to calculate the relative screen position while taking this flag into
+ * account, since it removes two lines from the edit window. */
 int no_help(void)
 {
     return ISSET(NO_HELP) ? 2 : 0;
 }
 
+/* Indicate a disabled function on the statusbar. */
 void nano_disabled_msg(void)
 {
     statusbar(_("Sorry, support for this function has been disabled"));
@@ -902,11 +920,14 @@ void do_exit(void)
 {
     int i;
 
+    /* If the file hasn't been modified, pretend the user chose not to
+     * save. */
     if (!openfile->modified)
-	/* Pretend the user chose not to save. */
 	i = 0;
+    /* If the TEMP_FILE flag is set, pretend the user chose to save. */
     else if (ISSET(TEMP_FILE))
 	i = 1;
+    /* Otherwise, ask the user whether or not to save. */
     else
 	i = do_yesno_prompt(FALSE,
 		_("Save modified buffer (ANSWERING \"No\" WILL DESTROY CHANGES) ? "));
@@ -915,18 +936,22 @@ void do_exit(void)
     dump_filestruct(openfile->fileage);
 #endif
 
+    /* If the user chose not to save, or if the user chose to save and
+     * the save succeeded, we're ready to exit. */
     if (i == 0 || (i == 1 && do_writeout(TRUE) == 0)) {
 #ifdef ENABLE_MULTIBUFFER
 	/* Exit only if there are no more open file buffers. */
 	if (!close_buffer())
 #endif
 	    finish();
+    /* If the user canceled, we go on. */
     } else if (i != 1)
 	statusbar(_("Cancelled"));
 
     display_main_list();
 }
 
+/* Initialize the signal handlers. */
 void signal_init(void)
 {
     /* Trap SIGINT and SIGQUIT because we want them to do useful
@@ -1005,6 +1030,7 @@ RETSIGTYPE do_continue(int signal)
 }
 
 #ifndef NANO_TINY
+/* Handler for SIGWINCH (window size change). */
 RETSIGTYPE handle_sigwinch(int signal)
 {
     const char *tty = ttyname(0);
@@ -1079,6 +1105,9 @@ RETSIGTYPE handle_sigwinch(int signal)
     siglongjmp(jmpbuf, 1);
 }
 
+/* If allow is TRUE, block any SIGWINCH signals that we get, so that we
+ * can deal with them later.  If allow is FALSE, unblock any SIGWINCH
+ * signals that we have, so that we can deal with them now. */
 void allow_pending_sigwinch(bool allow)
 {
     sigset_t winch;
@@ -1089,6 +1118,7 @@ void allow_pending_sigwinch(bool allow)
 #endif /* !NANO_TINY */
 
 #ifndef NANO_TINY
+/* Handle the global toggle specified in which. */
 void do_toggle(const toggle *which)
 {
     bool enabled;
@@ -1139,6 +1169,8 @@ void do_toggle(const toggle *which)
 }
 #endif /* !NANO_TINY */
 
+/* Disable extended input and output processing in our terminal
+ * settings. */
 void disable_extended_io(void)
 {
     struct termios term;
@@ -1149,6 +1181,8 @@ void disable_extended_io(void)
     tcsetattr(0, TCSANOW, &term);
 }
 
+/* Disable interpretation of the special control keys in our terminal
+ * settings. */
 void disable_signals(void)
 {
     struct termios term;
@@ -1159,6 +1193,8 @@ void disable_signals(void)
 }
 
 #ifndef NANO_TINY
+/* Enable interpretation of the special control keys in our terminal
+ * settings. */
 void enable_signals(void)
 {
     struct termios term;
@@ -1169,6 +1205,8 @@ void enable_signals(void)
 }
 #endif
 
+/* Disable interpretation of the flow control characters in our terminal
+ * settings. */
 void disable_flow_control(void)
 {
     struct termios term;
@@ -1178,6 +1216,8 @@ void disable_flow_control(void)
     tcsetattr(0, TCSANOW, &term);
 }
 
+/* Enable interpretation of the flow control characters in our terminal
+ * settings. */
 void enable_flow_control(void)
 {
     struct termios term;
@@ -1206,6 +1246,15 @@ void terminal_init(void)
 	disable_flow_control();
 }
 
+/* Read in a character, interpret it as a shortcut or toggle if
+ * necessary, and return it.  Set meta_key to TRUE if the character is a
+ * meta sequence, set func_key to TRUE if the character is a function
+ * key, set s_or_t to TRUE if the character is a shortcut or toggle
+ * key, set ran_func to TRUE if we ran a function associated with a
+ * shortcut key, and set finished to TRUE if we're done after running
+ * or trying to run a function associated with a shortcut key.  If
+ * allow_funcs is FALSE, don't actually run any functions associated
+ * with shortcut keys. */
 int do_input(bool *meta_key, bool *func_key, bool *s_or_t, bool
 	*ran_func, bool *finished, bool allow_funcs)
 {
@@ -1325,8 +1374,8 @@ int do_input(bool *meta_key, bool *func_key, bool *s_or_t, bool
 		/* Handle the normal edit window shortcuts, setting
 		 * ran_func to TRUE if we try to run their associated
 		 * functions and setting finished to TRUE to indicate
-		 * that we're done after trying to run their associated
+		 * that we're done after running or trying to run their
-		 * functions. */
+		 * associated functions. */
 		default:
 		    /* Blow away the text in the cutbuffer if we aren't
 		     * cutting text. */
@@ -1364,6 +1413,7 @@ int do_input(bool *meta_key, bool *func_key, bool *s_or_t, bool
 }
 
 #ifndef DISABLE_MOUSE
+/* Handle a mouse click on the edit window or the shortcut list. */
 bool do_mouse(void)
 {
     int mouse_x, mouse_y;
@@ -2095,5 +2145,6 @@ int main(int argc, char **argv)
 		TRUE);
     }
 
+    /* We should never get here. */
     assert(FALSE);
 }

src/nano.h

@@ -64,15 +64,17 @@
 #endif
 
 #ifdef USE_SLANG
-/* Slang support enabled. */
+/* Slang support. */
 #include <slcurses.h>
 /* Slang curses emulation brain damage, part 2: Slang doesn't define the
  * curses equivalents of the Insert or Delete keys. */
 #define KEY_DC SL_KEY_DELETE
 #define KEY_IC SL_KEY_IC
+/* Ncurses support. */
 #elif defined(HAVE_NCURSES_H)
 #include <ncurses.h>
-#else /* Uh oh. */
+#else
+/* Curses support. */
 #include <curses.h>
 #endif /* CURSES_H */
 
@@ -172,81 +174,116 @@ typedef enum {
 /* Structure types. */
 typedef struct filestruct {
     char *data;
-    struct filestruct *next;	/* Next node. */
+	/* The text of this line. */
-    struct filestruct *prev;	/* Previous node. */
+    ssize_t lineno;
-    ssize_t lineno;		/* The line number. */
+	/* The number of this line. */
+    struct filestruct *next;
+	/* Next node. */
+    struct filestruct *prev;
+	/* Previous node. */
 } filestruct;
 
 typedef struct partition {
     filestruct *fileage;
+	/* The top line of this portion of the file. */
     filestruct *top_prev;
+	/* The line before the top line of this portion of the file. */
     char *top_data;
+	/* The text before the beginning of the top line of this portion
+	 * of the file. */
     filestruct *filebot;
+	/* The bottom line of this portion of the file. */
     filestruct *bot_next;
+	/* The line after the bottom line of this portion of the
+	 * file. */
     char *bot_data;
+	/* The text after the end of the bottom line of this portion of
+	 * the file. */
 } partition;
 
 #ifdef ENABLE_COLOR
 typedef struct colortype {
-    short fg;			/* Foreground color. */
+    short fg;
-    short bg;			/* Background color. */
+	/* This syntax's foreground color. */
-    bool bright;		/* Is this color A_BOLD? */
+    short bg;
-    bool icase;			/* Is this regex string case
+	/* This syntax's background color. */
-				 * insensitive? */
+    bool bright;
-    int pairnum;		/* Color pair number used for this
+	/* Is this color A_BOLD? */
-				 * foreground/background. */
+    bool icase;
-    char *start_regex;		/* Start (or all) of the regex
+	/* Is this regex string case insensitive? */
-				 * string. */
+    int pairnum;
-    regex_t *start;		/* Compiled start (or all) of the regex
+	/* The color pair number used for this foreground color and
-				 * string. */
+	 * background color. */
-    char *end_regex;		/* End (if any) of the regex string. */
+    char *start_regex;
-    regex_t *end;		/* Compiled end (if any) of the regex
+	/* The start (or all) of the regex string. */
-				 * string. */
+    regex_t *start;
+	/* The compiled start (or all) of the regex string. */
+    char *end_regex;
+	/* The end (if any) of the regex string. */
+    regex_t *end;
+	/* The compiled end (if any) of the regex string. */
     struct colortype *next;
+	/* Next set of colors. */
 } colortype;
 
 typedef struct exttype {
-    char *ext_regex;		/* Extensions that match this syntax. */
+    char *ext_regex;
-    regex_t *ext;		/* Compiled extensions that match this
+	/* The extensions that match this syntax. */
-				 * syntax. */
+    regex_t *ext;
+	/* The compiled extensions that match this syntax. */
     struct exttype *next;
+	/* Next set of extensions. */
 } exttype;
 
 typedef struct syntaxtype {
-    char *desc;			/* Name of this syntax type. */
+    char *desc;
-    exttype *extensions;	/* List of extensions that this syntax
+	/* The name of this syntax. */
-				 * applies to. */
+    exttype *extensions;
-    colortype *color;		/* Color struct for this syntax. */
+	/* The list of extensions that this syntax applies to. */
+    colortype *color;
+	/* The colors used in this syntax. */
     struct syntaxtype *next;
+	/* Next syntax. */
 } syntaxtype;
 #endif /* ENABLE_COLOR */
 
 typedef struct openfilestruct {
-    char *filename;		/* Current file's name. */
+    char *filename;
-    filestruct *fileage;	/* Current file's first line. */
+	/* The current file's name. */
-    filestruct *filebot;	/* Current file's last line. */
+    filestruct *fileage;
-    filestruct *edittop;	/* Current top of edit window. */
+	/* The current file's first line. */
-    filestruct *current;	/* Current file's line. */
+    filestruct *filebot;
-    size_t totsize;		/* Current file's total number of
+	/* The current file's last line. */
-				 * characters. */
+    filestruct *edittop;
-    size_t current_x;		/* Current file's x-coordinate
+	/* The current top of the edit window. */
-				 * position. */
+    filestruct *current;
-    size_t placewewant;		/* Current file's place we want. */
+	/* The current file's current line. */
-    ssize_t current_y;		/* Current file's y-coordinate
+    size_t totsize;
-				 * position. */
+	/* The current file's total number of characters. */
-    bool modified;		/* Current file's modification
+    size_t current_x;
-				 * status. */
+	/* The current file's x-coordinate position. */
+    size_t placewewant;
+	/* The current file's place we want. */
+    ssize_t current_y;
+	/* The current file's y-coordinate position. */
+    bool modified;
+	/* Whether the current file has been modified. */
 #ifndef NANO_TINY
-    bool mark_set;		/* Current file's marking status. */
+    bool mark_set;
-    filestruct *mark_begin;	/* Current file's beginning marked
+	/* Whether the mark is on in the current file. */
-				 * line. */
+    filestruct *mark_begin;
-    size_t mark_begin_x;	/* Current file's beginning marked
+	/* The current file's beginning marked line, if any. */
-				 * line's x-coordinate position. */
+    size_t mark_begin_x;
-    file_format fmt;		/* Current file's format. */
+	/* The current file's beginning marked line's x-coordinate
-    struct stat *current_stat;	/* Current file's stat. */
+	 * position, if any. */
+    file_format fmt;
+	/* The current file's format. */
+    struct stat *current_stat;
+	/* The current file's stat. */
 #endif
 #ifdef ENABLE_COLOR
-    colortype *colorstrings;	/* Current file's associated colors. */
+    colortype *colorstrings;
+	/* The current file's associated colors. */
 #endif
     struct openfilestruct *next;
 	/* Next node. */
@@ -256,36 +293,49 @@ typedef struct openfilestruct {
 
 typedef struct shortcut {
     /* Key values that aren't used should be set to NANO_NO_KEY. */
-    int ctrlval;	/* Special sentinel key or control key we want
+    int ctrlval;
-			 * bound. */
+	/* The special sentinel key or control key we want bound, if
-    int metaval;	/* Meta key we want bound. */
+	 * any. */
-    int funcval;	/* Function key we want bound. */
+    int metaval;
-    int miscval;	/* Other Meta key we want bound. */
+	/* The meta key we want bound, if any. */
-    bool viewok;	/* Is this function legal in view mode? */
+    int funcval;
-    void (*func)(void);	/* Function to call when we catch this key. */
+	/* The function key we want bound, if any. */
-    const char *desc;	/* Description, e.g. "Page Up". */
+    int miscval;
+	/* The other meta key we want bound, if any. */
+    bool viewok;
+	/* Is this function allowed when in view mode? */
+    void (*func)(void);
+	/* The function to call when we get this key. */
+    const char *desc;
+	/* The function's description, e.g. "Page Up". */
 #ifndef DISABLE_HELP
-    const char *help;	/* Help file entry text. */
+    const char *help;
+	/* The help file entry text for this function. */
 #endif
     struct shortcut *next;
+	/* Next shortcut. */
 } shortcut;
 
 #ifndef NANO_TINY
 typedef struct toggle {
-   int val;		/* Sequence to toggle the key.  Should only need
+   int val;
-			 * one. */
+	/* The sequence to toggle the key.  We should only need one. */
-   const char *desc;	/* Description for when toggle is, uh, toggled,
+   const char *desc;
-			 * e.g. "Cut to end"; we'll append Enabled or
+	/* The description for when the toggle is, uh, toggled, e.g.
-			 * Disabled. */
+	 * "Cut to end"; we'll append Enabled or Disabled. */
-   long flag;		/* What flag actually gets toggled. */
+   long flag;
+	/* Which flag actually gets toggled. */
    struct toggle *next;
+	/* Next toggle. */
 } toggle;
 #endif
 
 #ifdef ENABLE_NANORC
 typedef struct rcoption {
    const char *name;
+	/* The name of the rcfile option. */
    long flag;
+	/* The flag associated with it, if any. */
 } rcoption;
 #endif
 
@@ -452,8 +502,8 @@ typedef struct rcoption {
 #define NANO_REFRESH_KEY	NANO_CONTROL_L
 #define NANO_JUSTIFY_KEY	NANO_CONTROL_J
 #define NANO_JUSTIFY_FKEY	KEY_F(4)
-#define NANO_UNJUSTIFY_KEY	NANO_UNCUT_KEY	/* Same key as uncut. */
+#define NANO_UNJUSTIFY_KEY	NANO_UNCUT_KEY	/* Same key as UnCut. */
-#define NANO_UNJUSTIFY_FKEY	NANO_UNCUT_FKEY	/* Same key as uncut. */
+#define NANO_UNJUSTIFY_FKEY	NANO_UNCUT_FKEY	/* Same key as UnCut. */
 #define NANO_PREVLINE_KEY	NANO_CONTROL_P
 #define NANO_NEXTLINE_KEY	NANO_CONTROL_N
 #define NANO_FORWARD_KEY	NANO_CONTROL_F
@@ -524,23 +574,23 @@ typedef struct rcoption {
 #define VIEW TRUE
 #define NOVIEW FALSE
 
-/* Minimum editor window columns and rows required for nano to work
+/* The minimum editor window columns and rows required for nano to work
  * correctly. */
 #define MIN_EDITOR_COLS 4
 #define MIN_EDITOR_ROWS 1
 
-/* Default number of characters from end-of-line where text wrapping
+/* The default number of characters from the end of the line where
- * occurs. */
+ * wrapping occurs. */
 #define CHARS_FROM_EOL 8
 
-/* Default width of a tab. */
+/* The default width of a tab in spaces. */
 #define WIDTH_OF_TAB 8
 
-/* Maximum number of search/replace history strings saved, not counting
+/* The maximum number of search/replace history strings saved, not
- * the blank lines at their ends. */
+ * counting the blank lines at their ends. */
 #define MAX_SEARCH_HISTORY 100
 
-/* Maximum number of bytes we read from a file at one time. */
+/* The maximum number of bytes we read from a file at one time. */
 #define MAX_BUF_SIZE 128
 
 #endif /* !NANO_H */

src/prompt.c

@@ -38,6 +38,15 @@ static bool reset_statusbar_x = FALSE;
 				/* Should we reset the cursor position
 				 * at the statusbar prompt? */
 
+/* Read in a character, interpret it as a shortcut or toggle if
+ * necessary, and return it.  Set meta_key to TRUE if the character is a
+ * meta sequence, set func_key to TRUE if the character is a function
+ * key, set s_or_t to TRUE if the character is a shortcut or toggle
+ * key, set ran_func to TRUE if we ran a function associated with a
+ * shortcut key, and set finished to TRUE if we're done after running
+ * or trying to run a function associated with a shortcut key.  If
+ * allow_funcs is FALSE, don't actually run any functions associated
+ * with shortcut keys. */
 int do_statusbar_input(bool *meta_key, bool *func_key, bool *s_or_t,
 	bool *ran_func, bool *finished, bool allow_funcs)
 {
@@ -75,7 +84,7 @@ int do_statusbar_input(bool *meta_key, bool *func_key, bool *s_or_t,
      * statusbar prompt shortcut, set have_shortcut to TRUE. */
     have_shortcut = (s != NULL || input == NANO_REFRESH_KEY ||
 	input == NANO_HOME_KEY || input == NANO_END_KEY ||
-	input == NANO_FORWARD_KEY || input == NANO_BACK_KEY ||
+	input == NANO_BACK_KEY || input == NANO_FORWARD_KEY ||
 	input == NANO_BACKSPACE_KEY || input == NANO_DELETE_KEY ||
 	input == NANO_CUT_KEY ||
 #ifndef NANO_TINY
@@ -152,12 +161,12 @@ int do_statusbar_input(bool *meta_key, bool *func_key, bool *s_or_t,
 		case NANO_END_KEY:
 		    do_statusbar_end();
 		    break;
-		case NANO_FORWARD_KEY:
-		    do_statusbar_right();
-		    break;
 		case NANO_BACK_KEY:
 		    do_statusbar_left();
 		    break;
+		case NANO_FORWARD_KEY:
+		    do_statusbar_right();
+		    break;
 		case NANO_BACKSPACE_KEY:
 		    /* If we're using restricted mode, the filename
 		     * isn't blank, and we're at the "Write File"
@@ -223,8 +232,8 @@ int do_statusbar_input(bool *meta_key, bool *func_key, bool *s_or_t,
 		/* Handle the normal statusbar prompt shortcuts, setting
 		 * ran_func to TRUE if we try to run their associated
 		 * functions and setting finished to TRUE to indicate
-		 * that we're done after trying to run their associated
+		 * that we're done after running or trying to run their
-		 * functions. */
+		 * associated functions. */
 		default:
 		    if (s->func != NULL) {
 			*ran_func = TRUE;
@@ -240,6 +249,7 @@ int do_statusbar_input(bool *meta_key, bool *func_key, bool *s_or_t,
 }
 
 #ifndef DISABLE_MOUSE
+/* Handle a mouse click on the statusbar prompt or the shortcut list. */
 bool do_statusbar_mouse(void)
 {
     int mouse_x, mouse_y;
@@ -342,6 +352,10 @@ void do_statusbar_output(char *output, size_t output_len, bool
     update_statusbar_line(answer, statusbar_x);
 }
 
+/* Move to the beginning of the prompt text.  If the SMART_HOME flag is
+ * set, move to the first non-whitespace character of the prompt text if
+ * we're not already there, or to the beginning of the prompt text if we
+ * are. */
 void do_statusbar_home(void)
 {
     size_t pww_save = statusbar_pww;
@@ -369,6 +383,7 @@ void do_statusbar_home(void)
 	update_statusbar_line(answer, statusbar_x);
 }
 
+/* Move to the end of the prompt text. */
 void do_statusbar_end(void)
 {
     size_t pww_save = statusbar_pww;
@@ -380,19 +395,7 @@ void do_statusbar_end(void)
 	update_statusbar_line(answer, statusbar_x);
 }
 
-void do_statusbar_right(void)
+/* Move left one character. */
-{
-    if (statusbar_x < strlen(answer)) {
-	size_t pww_save = statusbar_pww;
-
-	statusbar_x = move_mbright(answer, statusbar_x);
-	statusbar_pww = statusbar_xplustabs();
-
-	if (need_statusbar_horizontal_update(pww_save))
-	    update_statusbar_line(answer, statusbar_x);
-    }
-}
-
 void do_statusbar_left(void)
 {
     if (statusbar_x > 0) {
@@ -406,6 +409,21 @@ void do_statusbar_left(void)
     }
 }
 
+/* Move right one character. */
+void do_statusbar_right(void)
+{
+    if (statusbar_x < strlen(answer)) {
+	size_t pww_save = statusbar_pww;
+
+	statusbar_x = move_mbright(answer, statusbar_x);
+	statusbar_pww = statusbar_xplustabs();
+
+	if (need_statusbar_horizontal_update(pww_save))
+	    update_statusbar_line(answer, statusbar_x);
+    }
+}
+
+/* Backspace over one character. */
 void do_statusbar_backspace(void)
 {
     if (statusbar_x > 0) {
@@ -414,6 +432,7 @@ void do_statusbar_backspace(void)
     }
 }
 
+/* Delete one character. */
 void do_statusbar_delete(void)
 {
     statusbar_pww = statusbar_xplustabs();
@@ -435,7 +454,7 @@ void do_statusbar_delete(void)
     }
 }
 
-/* Move text from the statusbar prompt into oblivion. */
+/* Move text from the prompt into oblivion. */
 void do_statusbar_cut_text(void)
 {
     assert(answer != NULL);
@@ -456,9 +475,9 @@ void do_statusbar_cut_text(void)
 }
 
 #ifndef NANO_TINY
-/* Move to the next word at the statusbar prompt.  If allow_punct is
+/* Move to the next word in the prompt text.  If allow_punct is TRUE,
- * TRUE, treat punctuation as part of a word.  Return TRUE if we started
+ * treat punctuation as part of a word.  Return TRUE if we started on a
- * on a word, and FALSE otherwise. */
+ * word, and FALSE otherwise. */
 bool do_statusbar_next_word(bool allow_punct)
 {
     size_t pww_save = statusbar_pww;
@@ -521,7 +540,7 @@ bool do_statusbar_next_word(bool allow_punct)
     return started_on_word;
 }
 
-/* Move to the previous word at the statusbar prompt.  If allow_punct is
+/* Move to the previous word in the prompt text.  If allow_punct is
  * TRUE, treat punctuation as part of a word.  Return TRUE if we started
  * on a word, and FALSE otherwise. */
 bool do_statusbar_prev_word(bool allow_punct)
@@ -617,6 +636,8 @@ bool do_statusbar_prev_word(bool allow_punct)
 }
 #endif /* !NANO_TINY */
 
+/* Get verbatim input.  Set got_enter to TRUE if we got the Enter key as
+ * part of the verbatim input. */
 void do_statusbar_verbatim_input(bool *got_enter)
 {
     int *kbinput;
@@ -642,6 +663,10 @@ void do_statusbar_verbatim_input(bool *got_enter)
 }
 
 #ifndef NANO_TINY
+/* Search for a match to one of the two characters in bracket_set.  If
+ * reverse is TRUE, search backwards for the leftmost bracket.
+ * Otherwise, search forwards for the rightmost bracket.  Return TRUE if
+ * we found a match, and FALSE otherwise. */
 bool find_statusbar_bracket_match(bool reverse, const char
 	*bracket_set)
 {
@@ -681,6 +706,8 @@ bool find_statusbar_bracket_match(bool reverse, const char
     return TRUE;
 }
 
+/* Search for a match to the bracket at the current cursor position, if
+ * there is one. */
 void do_statusbar_find_bracket(void)
 {
     size_t statusbar_x_save, pww_save;

src/proto.h

@@ -24,17 +24,29 @@
 #ifndef PROTO_H
 #define PROTO_H 1
 
-/* Public externs. */
 #include "nano.h"
 
+/* Public externs.  See global.c for descriptions of them. */
 #ifndef DISABLE_WRAPJUSTIFY
 extern ssize_t fill;
 extern ssize_t wrap_at;
 #endif
-extern int editwinrows;
+
+extern char *last_search;
+extern char *last_replace;
+
 extern long flags;
-extern ssize_t tabsize;
+extern WINDOW *topwin;
-extern int currslen;
+extern WINDOW *edit;
+extern WINDOW *bottomwin;
+extern int editwinrows;
+
+extern filestruct *cutbuffer;
+#ifndef DISABLE_JUSTIFY
+extern filestruct *jusbuffer;
+#endif
+extern partition *filepart;
+extern openfilestruct *openfile;
 
 #if !defined(NANO_TINY) && defined(ENABLE_NANORC)
 extern char *whitespace;
@@ -54,41 +66,29 @@ extern size_t quotelen;
 #endif
 #endif
 
+extern char *answer;
+
+extern ssize_t tabsize;
+
 #ifndef NANO_TINY
 extern char *backup_dir;
 #endif
-
-extern WINDOW *topwin, *edit, *bottomwin;
-extern char *answer;
-extern char *last_search;
-extern char *last_replace;
 #ifndef DISABLE_OPERATINGDIR
 extern char *operating_dir;
 extern char *full_operating_dir;
 #endif
+
 #ifndef DISABLE_SPELLER
 extern char *alt_speller;
 #endif
 
-extern struct stat fileinfo;
+extern shortcut *main_list;
-extern filestruct *cutbuffer;
+extern shortcut *whereis_list;
-#ifndef DISABLE_JUSTIFY
+extern shortcut *replace_list;
-extern filestruct *jusbuffer;
-#endif
-extern partition *filepart;
-
-extern openfilestruct *openfile;
-
-#ifdef ENABLE_COLOR
-extern syntaxtype *syntaxes;
-extern char *syntaxstr;
-#endif
-
-extern shortcut *shortcut_list;
-extern shortcut *main_list, *whereis_list;
-extern shortcut *replace_list, *gotoline_list;
-extern shortcut *writefile_list, *insertfile_list;
 extern shortcut *replace_list_2;
+extern shortcut *gotoline_list;
+extern shortcut *writefile_list;
+extern shortcut *insertfile_list;
 #ifndef NANO_TINY
 extern shortcut *extcmd_list;
 #endif
@@ -99,20 +99,16 @@ extern shortcut *help_list;
 extern shortcut *spell_list;
 #endif
 #ifndef DISABLE_BROWSER
-extern shortcut *browser_list, *gotodir_list;
+extern shortcut *browser_list;
+extern shortcut *gotodir_list;
+#endif
+
+#ifdef ENABLE_COLOR
+extern syntaxtype *syntaxes;
+extern char *syntaxstr;
 #endif
 
 extern const shortcut *currshortcut;
-
-#ifdef HAVE_REGEX_H
-extern regex_t search_regexp;
-extern regmatch_t regmatches[10];
-#ifdef ENABLE_COLOR
-extern regex_t syntaxfile_regexp;
-extern regmatch_t synfilematches[1];
-#endif
-#endif
-
 #ifndef NANO_TINY
 extern toggle *toggles;
 #endif
@@ -126,12 +122,15 @@ extern filestruct *replaceage;
 extern filestruct *replacebot;
 #endif
 
+#ifdef HAVE_REGEX_H
+extern regex_t search_regexp;
+extern regmatch_t regmatches[10];
+#endif
+
 extern bool curses_ended;
 
 extern char *homedir;
 
-/* The functions we want available. */
-
 /* Public functions in browser.c. */
 #ifndef DISABLE_BROWSER
 char *do_browser(char *path, DIR *dir);
@@ -436,8 +435,8 @@ void do_statusbar_output(char *output, size_t output_len, bool
 	*got_enter, bool allow_cntrls);
 void do_statusbar_home(void);
 void do_statusbar_end(void);
-void do_statusbar_right(void);
 void do_statusbar_left(void);
+void do_statusbar_right(void);
 void do_statusbar_backspace(void);
 void do_statusbar_delete(void);
 void do_statusbar_cut_text(void);
@@ -496,7 +495,7 @@ int regexp_init(const char *regexp);
 void regexp_cleanup(void);
 #endif
 void not_found_msg(const char *str);
-void search_abort(void);
+void search_replace_abort(void);
 void search_init_globals(void);
 int search_init(bool replacing, bool use_answer);
 bool findnextstr(
@@ -510,7 +509,6 @@ void do_search(void);
 #ifndef NANO_TINY
 void do_research(void);
 #endif
-void replace_abort(void);
 #ifdef HAVE_REGEX_H
 int replace_regexp(char *string, bool create);
 #endif
@@ -526,7 +524,7 @@ void do_gotolinecolumn(ssize_t line, ssize_t column, bool use_answer,
 	bool interactive, bool save_pos, bool allow_update);
 void do_gotolinecolumn_void(void);
 #ifndef DISABLE_SPELLER
-void do_gotopos(ssize_t line, size_t pos_x, ssize_t pos_y, size_t
+void do_gotopos(ssize_t pos_line, size_t pos_x, ssize_t pos_y, size_t
 	pos_pww);
 #endif
 #ifndef NANO_TINY
@@ -621,7 +619,7 @@ ssize_t ngetdelim(char **lineptr, size_t *n, int delim, FILE *stream);
 int safe_regexec(const regex_t *preg, const char *string, size_t nmatch,
 	regmatch_t pmatch[], int eflags);
 #endif
-int regexp_bol_or_eol(const regex_t *preg, const char *string);
+bool regexp_bol_or_eol(const regex_t *preg, const char *string);
 #endif
 #ifndef DISABLE_SPELLER
 bool is_whole_word(size_t pos, const char *buf, const char *word);

src/rcfile.c

@@ -93,8 +93,12 @@ const static rcoption rcopts[] = {
 };
 
 static bool errors = FALSE;
+	/* Whether we got any errors while parsing an rcfile. */
 static size_t lineno = 0;
+	/* If we did, the line number where the current error
+	 * occurred. */
 static char *nanorc = NULL;
+	/* The path to the rcfile we're parsing. */
 #ifdef ENABLE_COLOR
 static syntaxtype *endsyntax = NULL;
 	/* The end of the list of syntaxes. */
@@ -180,6 +184,8 @@ char *parse_argument(char *ptr)
 }
 
 #ifdef ENABLE_COLOR
+/* Return the short value corresponding to the color named in colorname,
+ * and set bright to TRUE if that color is bright. */
 short color_to_short(const char *colorname, bool *bright)
 {
     short mcolor = -1;
@@ -217,6 +223,7 @@ short color_to_short(const char *colorname, bool *bright)
     return mcolor;
 }
 
+/* Parse the next regex string from the line at ptr, and return it. */
 char *parse_next_regex(char *ptr)
 {
     assert(ptr != NULL);
@@ -265,6 +272,8 @@ bool nregcomp(const char *regex, int eflags)
     return (rc == 0);
 }
 
+/* Parse the next syntax string from the line at ptr, and add it to the
+ * global list of color syntaxes. */
 void parse_syntax(char *ptr)
 {
     const char *fileregptr = NULL, *nameptr = NULL;
@@ -372,8 +381,9 @@ void parse_syntax(char *ptr)
     }
 }
 
-/* Parse the color stuff into the colorstrings array.  If icase is TRUE,
+/* Parse the color string in the line at ptr, and add it to the current
- * treat the color stuff as case insensitive. */
+ * file's associated colors.  If icase is TRUE, treat the color string
+ * as case insensitive. */
 void parse_colors(char *ptr, bool icase)
 {
     short fg, bg;
@@ -529,7 +539,8 @@ void parse_colors(char *ptr, bool icase)
 }
 #endif /* ENABLE_COLOR */
 
-/* Parse the rcfile, once it has been opened successfully. */
+/* Parse the rcfile, once it has been opened successfully at
+ * rcstream. */
 void parse_rcfile(FILE *rcstream)
 {
     char *buf = NULL;

src/search.c

@@ -68,6 +68,8 @@ int regexp_init(const char *regexp)
     return 1;
 }
 
+/* Decompile the compiled regular expression we used in the last
+ * search, if any. */
 void regexp_cleanup(void)
 {
     if (regexp_compiled) {
@@ -77,6 +79,8 @@ void regexp_cleanup(void)
 }
 #endif
 
+/* Indicate on the statusbar that the string at str was not found by the
+ * last search. */
 void not_found_msg(const char *str)
 {
     char *disp;
@@ -93,7 +97,11 @@ void not_found_msg(const char *str)
     free(disp);
 }
 
-void search_abort(void)
+/* Abort the current search or replace.  Clean up by displaying the main
+ * shortcut list, updating the screen if the mark was on before, and
+ * decompiling the compiled regular expression we used in the last
+ * search, if any. */
+void search_replace_abort(void)
 {
     display_main_list();
 #ifndef NANO_TINY
@@ -105,6 +113,7 @@ void search_abort(void)
 #endif
 }
 
+/* Initialize the global search and replace strings. */
 void search_init_globals(void)
 {
     if (last_search == NULL)
@@ -403,6 +412,8 @@ bool findnextstr(
     return TRUE;
 }
 
+/* Clear the flag indicating that a search reached the last line of the
+ * file.  We need to do this just before a new search. */
 void findnextstr_wrap_reset(void)
 {
     search_last_line = FALSE;
@@ -424,7 +435,7 @@ void do_search(void)
     i = search_init(FALSE, FALSE);
     if (i == -1)	/* Cancel, Go to Line, blank search string, or
 			 * regcomp() failed. */
-	search_abort();
+	search_replace_abort();
     else if (i == -2)	/* Replace. */
 	do_replace();
 #if !defined(NANO_TINY) || defined(HAVE_REGEX_H)
@@ -487,11 +498,11 @@ void do_search(void)
 
     openfile->placewewant = xplustabs();
     edit_redraw(fileptr, old_pww);
-    search_abort();
+    search_replace_abort();
 }
 
 #ifndef NANO_TINY
-/* Search for the next string without prompting. */
+/* Search for the last string without prompting. */
 void do_research(void)
 {
     filestruct *fileptr = openfile->current;
@@ -553,16 +564,10 @@ void do_research(void)
 
     openfile->placewewant = xplustabs();
     edit_redraw(fileptr, old_pww);
-    search_abort();
+    search_replace_abort();
 }
 #endif
 
-void replace_abort(void)
-{
-    /* For now, we do the same thing as search_abort(). */
-    search_abort();
-}
-
 #ifdef HAVE_REGEX_H
 int replace_regexp(char *string, bool create)
 {
@@ -881,14 +886,14 @@ void do_replace(void)
 
     if (ISSET(VIEW_MODE)) {
 	print_view_warning();
-	replace_abort();
+	search_replace_abort();
 	return;
     }
 
     i = search_init(TRUE, FALSE);
     if (i == -1) {		/* Cancel, Go to Line, blank search
 				 * string, or regcomp() failed. */
-	replace_abort();
+	search_replace_abort();
 	return;
     } else if (i == -2) {	/* No Replace. */
 	do_search();
@@ -930,7 +935,7 @@ void do_replace(void)
 		answer = mallocstrcpy(answer, last_replace);
 	    statusbar(_("Cancelled"));
 	}
-	replace_abort();
+	search_replace_abort();
 	return;
     }
 
@@ -961,7 +966,7 @@ void do_replace(void)
 		"Replaced %lu occurrences", (unsigned long)numreplaced),
 		(unsigned long)numreplaced);
 
-    replace_abort();
+    search_replace_abort();
 }
 
 /* Go to the specified line and column, or ask for them if interactive
@@ -1035,6 +1040,7 @@ void do_gotolinecolumn(ssize_t line, ssize_t column, bool use_answer,
     display_main_list();
 }
 
+/* Go to the specified line and column, asking for them beforehand. */
 void do_gotolinecolumn_void(void)
 {
     do_gotolinecolumn(openfile->current->lineno,
@@ -1042,13 +1048,16 @@ void do_gotolinecolumn_void(void)
 }
 
 #ifndef DISABLE_SPELLER
-void do_gotopos(ssize_t line, size_t pos_x, ssize_t pos_y, size_t
+/* Go to the line with the number specified in pos_line, the
+ * x-coordinate specified in pos_x, the y-coordinate specified in pos_y,
+ * and the place we want specified in pos_pww. */
+void do_gotopos(ssize_t pos_line, size_t pos_x, ssize_t pos_y, size_t
 	pos_pww)
 {
     /* Since do_gotolinecolumn() resets the x-coordinate but not the
      * y-coordinate, set the coordinates up this way. */
     openfile->current_y = pos_y;
-    do_gotolinecolumn(line, pos_x + 1, FALSE, FALSE, TRUE, TRUE);
+    do_gotolinecolumn(pos_line, pos_x + 1, FALSE, FALSE, TRUE, TRUE);
 
     /* Set the rest of the coordinates up. */
     openfile->placewewant = pos_pww;
@@ -1058,8 +1067,9 @@ void do_gotopos(ssize_t line, size_t pos_x, ssize_t pos_y, size_t
 
 #ifndef NANO_TINY
 /* Search for a match to one of the two characters in bracket_set.  If
- * reverse is TRUE, search backwards.  Otherwise, search forwards.
+ * reverse is TRUE, search backwards for the leftmost bracket.
- * Return TRUE if we found a match, or FALSE otherwise. */
+ * Otherwise, search forwards for the rightmost bracket.  Return TRUE if
+ * we found a match, and FALSE otherwise. */
 bool find_bracket_match(bool reverse, const char *bracket_set)
 {
     filestruct *fileptr = openfile->current;

src/text.c

@@ -33,8 +33,8 @@
 
 #ifndef NANO_TINY
 static pid_t pid = -1;
-	/* The PID of the newly forked process in execute_command(), for
+	/* The PID of the forked process in execute_command(), for use
-	 * use with the cancel_command() signal handler. */
+	 * with the cancel_command() signal handler. */
 #endif
 #ifndef DISABLE_WRAPPING
 static bool prepend_wrap = FALSE;
@@ -46,6 +46,7 @@ static filestruct *jusbottom = NULL;
 #endif
 
 #ifndef NANO_TINY
+/* Toggle the mark. */
 void do_mark(void)
 {
     openfile->mark_set = !openfile->mark_set;
@@ -62,6 +63,7 @@ void do_mark(void)
 }
 #endif /* !NANO_TINY */
 
+/* Delete one character. */
 void do_delete(void)
 {
     bool do_refresh = FALSE;
@@ -150,6 +152,7 @@ void do_delete(void)
 	update_line(openfile->current, openfile->current_x);
 }
 
+/* Backspace over one character. */
 void do_backspace(void)
 {
     if (openfile->current != openfile->fileage ||
@@ -159,6 +162,8 @@ void do_backspace(void)
     }
 }
 
+/* Insert a tab.  If the TABS_TO_SPACES flag is set, insert the number
+ * of spaces that a tab would normally take up. */
 void do_tab(void)
 {
 #ifndef NANO_TINY
@@ -187,7 +192,7 @@ void do_tab(void)
 #endif
 }
 
-/* Someone hits Enter *gasp!* */
+/* Someone hits Enter/Return *gasp!* */
 void do_enter(void)
 {
     filestruct *newnode = make_new_node(openfile->current);
@@ -244,6 +249,8 @@ void do_enter(void)
 }
 
 #ifndef NANO_TINY
+/* Send a SIGKILL (unconditional kill) to the forked process in
+ * execute_command(). */
 RETSIGTYPE cancel_command(int signal)
 {
     if (kill(pid, SIGKILL) == -1)
@@ -341,6 +348,8 @@ bool execute_command(const char *command)
 #endif /* !NANO_TINY */
 
 #ifndef DISABLE_WRAPPING
+/* Clear the prepend_wrap flag.  We need to do this as soon as we do
+ * something other than type text. */
 void wrap_reset(void)
 {
     prepend_wrap = FALSE;
@@ -1555,11 +1564,13 @@ void do_justify(bool full_justify)
     display_main_list();
 }
 
+/* Justify the current paragraph. */
 void do_justify_void(void)
 {
     do_justify(FALSE);
 }
 
+/* Justify the entire file. */
 void do_full_justify(void)
 {
     do_justify(TRUE);
@@ -1732,9 +1743,9 @@ bool do_int_spell_fix(const char *word)
     return !canceled;
 }
 
-/* Integrated spell checking using the spell program, filtered through
+/* Internal (integrated) spell checking using the spell program,
- * the sort and uniq programs.  Return NULL for normal termination,
+ * filtered through the sort and uniq programs.  Return NULL for normal
- * and the error string otherwise. */
+ * termination, and the error string otherwise. */
 const char *do_int_speller(const char *tempfile_name)
 {
     char *read_buff, *read_buff_ptr, *read_buff_word;
@@ -1882,7 +1893,7 @@ const char *do_int_speller(const char *tempfile_name)
 	do_int_spell_fix(read_buff_word);
 
     free(read_buff);
-    replace_abort();
+    search_replace_abort();
     edit_refresh();
 
     /* Process the end of the spell process. */
@@ -1914,8 +1925,8 @@ const char *do_int_speller(const char *tempfile_name)
     exit(1);
 }
 
-/* External spell checking.  Return value: NULL for normal termination,
+/* External (alternate) spell checking.  Return NULL for normal
- * otherwise the error string. */
+ * termination, and the error string otherwise. */
 const char *do_alt_speller(char *tempfile_name)
 {
     int alt_spell_status;
@@ -2107,6 +2118,8 @@ const char *do_alt_speller(char *tempfile_name)
     return NULL;
 }
 
+/* Spell check the current file.  If an alternate spell checker is
+ * specified, use it.  Otherwise, use the internal spell checker. */
 void do_spell(void)
 {
     int i;
@@ -2220,6 +2233,7 @@ void do_wordlinechar_count(void)
 }
 #endif /* !NANO_TINY */
 
+/* Get verbatim input. */
 void do_verbatim_input(void)
 {
     int *kbinput;

src/utils.c

@@ -30,6 +30,7 @@
 #include <ctype.h>
 #include <errno.h>
 
+/* Return the number of decimal digits in n. */
 int digits(size_t n)
 {
     int i = 1;
@@ -249,7 +250,9 @@ int safe_regexec(const regex_t *preg, const char *string, size_t nmatch,
 }
 #endif
 
-int regexp_bol_or_eol(const regex_t *preg, const char *string)
+/* Do the compiled regex in preg and the regex in string match the
+ * beginning or end of a line? */
+bool regexp_bol_or_eol(const regex_t *preg, const char *string)
 {
     return (regexec(preg, string, 0, NULL, 0) == 0 &&
 	regexec(preg, string, 0, NULL, REG_NOTBOL | REG_NOTEOL) ==
@@ -361,7 +364,9 @@ void nperror(const char *s)
     }
 }
 
-/* Thanks, BG, many people have been asking for this... */
+/* This is a wrapper for the malloc() function that properly handles
+ * things when we run out of memory.  Thanks, BG, many people have been
+ * asking for this... */
 void *nmalloc(size_t howmuch)
 {
     void *r = malloc(howmuch);
@@ -372,6 +377,8 @@ void *nmalloc(size_t howmuch)
     return r;
 }
 
+/* This is a wrapper for the realloc() function that properly handles
+ * things when we run out of memory. */
 void *nrealloc(void *ptr, size_t howmuch)
 {
     void *r = realloc(ptr, howmuch);
@@ -511,11 +518,14 @@ void new_magicline(void)
 
 #ifndef NANO_TINY
 /* Remove the magicline from filebot, if there is one and it isn't the
- * only line in the file. */
+ * only line in the file.  Assume that edittop and current are not at
+ * filebot. */
 void remove_magicline(void)
 {
     if (openfile->filebot->data[0] == '\0' &&
 	openfile->filebot != openfile->fileage) {
+	assert(openfile->filebot != openfile->edittop && openfile->filebot != openfile->current);
+
 	openfile->filebot = openfile->filebot->prev;
 	free_filestruct(openfile->filebot->next);
 	openfile->filebot->next = NULL;

src/winio.c

@@ -1586,6 +1586,14 @@ bool get_mouseinput(int *mouse_x, int *mouse_y, bool allow_shortcuts)
 }
 #endif /* !DISABLE_MOUSE */
 
+/* Return the shortcut corresponding to the values of kbinput (the key
+ * itself), meta_key (whether the key is a meta sequence), and func_key
+ * (whether the key is a function key), if any.  The shortcut will be
+ * the first one in the list (control key, meta key sequence, function
+ * key, other meta key sequence) for the corresponding function.  For
+ * example, passing in a meta key sequence that corresponds to a
+ * function with a control key, a function key, and a meta key sequence
+ * will return the control key corresponding to that function. */
 const shortcut *get_shortcut(const shortcut *s_list, int *kbinput, bool
 	*meta_key, bool *func_key)
 {
@@ -1638,6 +1646,9 @@ const shortcut *get_shortcut(const shortcut *s_list, int *kbinput, bool
 }
 
 #ifndef NANO_TINY
+/* Return the global toggle corresponding to the values of kbinput (the
+ * key itself) and meta_key (whether the key is a meta sequence), if
+ * any. */
 const toggle *get_toggle(int kbinput, bool meta_key)
 {
     const toggle *t = toggles;
@@ -1667,17 +1678,22 @@ void blank_line(WINDOW *win, int y, int x, int n)
 	waddch(win, ' ');
 }
 
+/* Blank the first line of the top portion of the window. */
 void blank_titlebar(void)
 {
     blank_line(topwin, 0, 0, COLS);
 }
 
+/* If the MORE_SPACE flag isn't set, blank the second line of the top
+ * portion of the window. */
 void blank_topbar(void)
 {
     if (!ISSET(MORE_SPACE))
 	blank_line(topwin, 1, 0, COLS);
 }
 
+/* Blank all the lines of the middle portion of the window, i.e, the
+ * edit window. */
 void blank_edit(void)
 {
     int i;
@@ -1685,11 +1701,14 @@ void blank_edit(void)
 	blank_line(edit, i, 0, COLS);
 }
 
+/* Blank the first line of the bottom portion of the window. */
 void blank_statusbar(void)
 {
     blank_line(bottomwin, 0, 0, COLS);
 }
 
+/* If the NO_HELP flag isn't set, blank the last two lines of the bottom
+ * portion of the window. */
 void blank_bottombars(void)
 {
     if (!ISSET(NO_HELP)) {
@@ -1698,6 +1717,9 @@ void blank_bottombars(void)
     }
 }
 
+/* Check if the number of keystrokes needed to blank the statusbar has
+ * been pressed.  If so, blank the statusbar, unless constant cursor
+ * position display is on. */
 void check_statusblank(void)
 {
     if (statusblank > 0)
@@ -1872,6 +1894,12 @@ char *display_string(const char *buf, size_t start_col, size_t len, bool
     return converted;
 }
 
+/* Display the path specified in path on the titlebar, along with the
+ * current version of nano and whether the current file has been
+ * modified.  If path is NULL, assume we're in normal editing mode and
+ * display the current filename instead.  Otherwise, assume we're in the
+ * file browser, and don't display whether the current file has been
+ * modified. */
 void titlebar(const char *path)
 {
     int space = COLS;
@@ -2029,8 +2057,8 @@ void titlebar(const char *path)
     wnoutrefresh(edit);
 }
 
-/* Set the modified flag if it isn't already set, and then update the
+/* Mark the current file as modified if it isn't already, and then
- * titlebar. */
+ * update the titlebar to display the file's new status. */
 void set_modified(void)
 {
     if (!openfile->modified) {
@@ -2106,6 +2134,8 @@ void statusbar(const char *msg, ...)
 	25;
 }
 
+/* Display the shortcut list in s on the last two rows of the bottom
+ * portion of the window. */
 void bottombars(const shortcut *s)
 {
     size_t i, colwidth, slen;
@@ -2846,6 +2876,7 @@ void edit_update(update_type location)
     openfile->edittop = foo;
 }
 
+/* Unconditionally redraw the entire screen. */
 void total_redraw(void)
 {
 #ifdef USE_SLANG
@@ -2858,6 +2889,8 @@ void total_redraw(void)
 #endif
 }
 
+/* Unconditionally redraw the entire screen, and then refresh it using
+ * the current file. */
 void total_refresh(void)
 {
     total_redraw();
@@ -2866,6 +2899,8 @@ void total_refresh(void)
     bottombars(currshortcut);
 }
 
+/* Display the main shortcut list on the last two rows of the bottom
+ * portion of the window. */
 void display_main_list(void)
 {
     bottombars(main_list);
@@ -2921,6 +2956,7 @@ void do_cursorpos(bool constant)
     disable_cursorpos = FALSE;
 }
 
+/* Unconditionally display the current cursor position. */
 void do_cursorpos_void(void)
 {
     do_cursorpos(FALSE);