tweaks: improve a couple of comments

src/browser.c

@@ -659,15 +659,15 @@ void browser_select_dirname(const char *needle)
 	}
 }
 
-/* Set up the system variables for a filename search.  Return -1 or -2 if
+/* Prepare the prompt and ask the user what to search for.  Return -2
- * the search should be canceled (due to Cancel or a blank search string),
+ * for a blank answer, -1 for Cancel, 0 when we have a string, and a
- * return 0 when we have a string, and return a positive value when some
+ * positive value when some function was run. */
- * function was run. */
 int filesearch_init(void)
 {
 	int input;
 	char *buf;
 
+	/* If something was searched for before, show it between square brackets. */
 	if (*last_search != '\0') {
 		char *disp = display_string(last_search, 0, COLS / 3, FALSE);
 
@@ -679,18 +679,16 @@ int filesearch_init(void)
 	} else
 		buf = mallocstrcpy(NULL, "");
 
-	/* This is now one simple call.  It just does a lot. */
+	/* Now ask what to search for. */
 	input = do_prompt(FALSE, FALSE, MWHEREISFILE, NULL, &search_history,
-				browser_refresh, "%s%s", _("Search"), buf);
+						browser_refresh, "%s%s", _("Search"), buf);
-
-	/* Release buf now that we don't need it anymore. */
 	free(buf);
 
 	/* If only Enter was pressed but we have a previous string, it's okay. */
 	if (input == -2 && *last_search != '\0')
 		return 0;
 
-	/* Otherwise negative inputs are a bailout. */
+	/* Otherwise negative responses are a bailout. */
 	if (input < 0)
 		statusbar(_("Cancelled"));
 

src/nano.c

@@ -551,14 +551,15 @@ void say_there_is_no_help(void)
 }
 #endif
 
-/* Make nano exit gracefully. */
+/* Exit normally: restore the terminal state and save history files. */
 void finish(void)
 {
-	/* Blank the statusbar and (if applicable) the shortcut list,
+	/* Blank the statusbar and (if applicable) the shortcut list. */
-	 * and move the cursor to the last line of the screen. */
 	blank_statusbar();
 	blank_bottombars();
 	wrefresh(bottomwin);
+
+	/* Switch on the cursor and exit from curses mode. */
 	curs_set(1);
 	endwin();
 
@@ -582,7 +583,8 @@ void finish(void)
 	exit(0);
 }
 
-/* Make nano die gracefully. */
+/* Die gracefully -- by restoring the terminal state and saving any buffers
+ * that were modified. */
 void die(const char *msg, ...)
 {
 	va_list ap;

src/winio.c

@@ -1944,7 +1944,7 @@ char *display_string(const char *buf, size_t column, size_t span, bool isdata)
 			continue;
 		}
 
-		/* Represent an invalid sequence with the Replacement Character. */
+		/* Represent an invalid starter byte with the Replacement Character. */
 		converted[index++] = '\xEF';
 		converted[index++] = '\xBF';
 		converted[index++] = '\xBD';