Be a bit more consistent and proper.

4 files changed, 46 insertions, 59 deletions

diff --git a/fish.xcodeproj/project.pbxproj b/fish.xcodeproj/project.pbxproj
index 4234a516..721b5a82 100644
--- a/fish.xcodeproj/project.pbxproj
+++ b/fish.xcodeproj/project.pbxproj
@@ -569,7 +569,6 @@
 		D0A0854B13B3ACEE0099B651 /* intern.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = intern.cpp; sourceTree = "<group>"; };
 		D0A0854C13B3ACEE0099B651 /* io.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = io.cpp; sourceTree = "<group>"; };
 		D0A0854D13B3ACEE0099B651 /* iothread.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = iothread.cpp; sourceTree = "<group>"; };
-		D0A0854E13B3ACEE0099B651 /* key_reader.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = key_reader.cpp; sourceTree = "<group>"; };
 		D0A0854F13B3ACEE0099B651 /* kill.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = kill.cpp; sourceTree = "<group>"; };
 		D0A0855113B3ACEE0099B651 /* output.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = output.cpp; sourceTree = "<group>"; };
 		D0A0855213B3ACEE0099B651 /* parse_util.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = parse_util.cpp; sourceTree = "<group>"; };
@@ -805,7 +804,6 @@
 				D0A0854D13B3ACEE0099B651 /* iothread.cpp */,
 				D0A0851813B3ACEE0099B651 /* kill.h */,
 				D0A0854F13B3ACEE0099B651 /* kill.cpp */,
-				D0A0854E13B3ACEE0099B651 /* key_reader.cpp */,
 				D03EE83814DF88B200FC7150 /* lru.h */,
 				D0A0851A13B3ACEE0099B651 /* output.h */,
 				D0A0855113B3ACEE0099B651 /* output.cpp */,
diff --git a/src/autoload.cpp b/src/autoload.cpp
index 9a8ebf40..56292fc6 100644
--- a/src/autoload.cpp
+++ b/src/autoload.cpp
@@ -22,7 +22,7 @@
 #include "exec.h"
 #include "wutil.h"  // IWYU pragma: keep
 
-// The time before we'll recheck an autoloaded file.
+/// The time before we'll recheck an autoloaded file.
 static const int kAutoloadStalenessInterval = 15;
 
 file_access_attempt_t access_file(const wcstring &path, int mode) {
@@ -135,8 +135,9 @@ bool autoload_t::has_tried_loading(const wcstring &cmd) {
     return func != NULL;
 }
 
+/// @return Whether this function is stale.
+/// Internalized functions can never be stale.
 static bool is_stale(const autoload_function_t *func) {
-    // Return whether this function is stale. Internalized functions can never be stale.
     return !func->is_internalized &&
            time(NULL) - func->access.last_checked > kAutoloadStalenessInterval;
 }
@@ -159,14 +160,12 @@ autoload_function_t *autoload_t::get_autoloaded_function_with_creation(const wcs
 /// This internal helper function does all the real work. By using two functions, the internal
 /// function can return on various places in the code, and the caller can take care of various
 /// cleanup work.
-///
-///   cmd: the command name ('grep')
-///   really_load: whether to actually parse it as a function, or just check it it exists
-///   reload: whether to reload it if it's already loaded
-///   path_list: the set of paths to check
-///
-/// Result: if really_load is true, returns whether the function was loaded. Otherwise returns
-/// whether the function existed.
+/// @param cmd the command name ('grep')
+/// @param really_load Whether to actually parse it as a function, or just check it it exists
+/// @param reload Whether to reload it if it's already loaded
+/// @param path_list The set of paths to check
+/// @return If really_load is true, returns whether the function was loaded. Otherwise returns
+///         whether the function existed.
 bool autoload_t::locate_file_and_maybe_load_it(const wcstring &cmd, bool really_load, bool reload,
                                                const wcstring_list_t &path_list) {
     // Note that we are NOT locked in this function!
diff --git a/src/autoload.h b/src/autoload.h
index ef55fd94..efa8c16d 100644
--- a/src/autoload.h
+++ b/src/autoload.h
@@ -11,17 +11,17 @@
 #include "common.h"
 #include "lru.h"
 
-/// Recording an attempt to access a file.
+/// Record of an attempt to access a file.
 struct file_access_attempt_t {
-    /// modification time of the file
+    /// Modification time of the file
     time_t mod_time;
-    /// when we last checked the file
+    /// When we last checked the file
     time_t last_checked;
-    /// whether we believe we could access this file
+    /// Whether or not we believe we can access this file
     bool accessible;
-    /// whether the access attempt is stale
+    /// The access attempt is stale
     bool stale;
-    /// if we could not access the file, the error code
+    /// If we cannot access the file, the error code encountered.
     int error;
 };
 file_access_attempt_t access_file(const wcstring &path, int mode);
@@ -33,9 +33,10 @@ struct autoload_function_t : public lru_node_t {
           is_loaded(false),
           is_placeholder(false),
           is_internalized(false) {}
-    /// the last access attempt
+
+    /// The last access attempt recorded
     file_access_attempt_t access;
-    /// whether we have actually loaded this function
+    /// Have we actually loaded this function?
     bool is_loaded;
     /// Whether we are a placeholder that stands in for "no such function". If this is true, then
     /// is_loaded must be false.
@@ -51,24 +52,23 @@ struct builtin_script_t {
 
 class env_vars_snapshot_t;
 
-/// A class that represents a path from which we can autoload, and the autoloaded contents.
+/// Class representing a path from which we can autoload and the autoloaded contents.
 class autoload_t : private lru_cache_t<autoload_function_t> {
    private:
-    // Lock for thread safety.
+    /// Lock for thread safety.
     pthread_mutex_t lock;
-    // The environment variable name.
+    /// The environment variable name.
     const wcstring env_var_name;
-    // Builtin script array.
+    /// Builtin script array.
     const struct builtin_script_t *const builtin_scripts;
-    // Builtin script count.
+    /// Builtin script count.
     const size_t builtin_script_count;
-    // The path from which we most recently autoloaded.
+    /// The path from which we most recently autoloaded.
     wcstring last_path;
-    // That path, tokenized (split on separators).
+    /// the most reecently autoloaded path, tokenized (split on separators).
     wcstring_list_t last_path_tokenized;
-
-    // A table containing all the files that are currently being loaded. This is here to help
-    // prevent recursion.
+    /// A table containing all the files that are currently being loaded.
+    /// This is here to help prevent recursion.
     std::set<wcstring> is_loading_set;
 
     void remove_all_functions(void) { this->evict_all_nodes(); }
@@ -82,39 +82,31 @@ class autoload_t : private lru_cache_t<autoload_function_t> {
                                                                bool allow_eviction);
 
    protected:
-    // Overridable callback for when a command is removed.
+    /// Overridable callback for when a command is removed.
     virtual void command_removed(const wcstring &cmd) {}
 
    public:
-    // Create an autoload_t for the given environment variable name.
+    /// Create an autoload_t for the given environment variable name.
     autoload_t(const wcstring &env_var_name_var, const builtin_script_t *scripts,
                size_t script_count);
 
-    virtual ~autoload_t();  // destructor
-
-    // Autoload the specified file, if it exists in the specified path. Do not load it multiple
-    // times unless its timestamp changes or parse_util_unload is called.
-    //
-    // Autoloading one file may unload another.
-    //
-    // \param cmd the filename to search for. The suffix '.fish' is always added to this name
-    // \param on_unload a callback function to run if a suitable file is found, which has not
-    // already been run. unload will also be called for old files which are unloaded.
-    // \param reload wheter to recheck file timestamps on already loaded files
+    virtual ~autoload_t();
+
+    /// Autoload the specified file, if it exists in the specified path. Do not load it multiple
+    /// times unless its timestamp changes or parse_util_unload is called.
+    /// Autoloading one file may unload another.
+    /// @param cmd the filename to search for. The suffix '.fish' is always added to this name
+    /// @param reload wheter to recheck file timestamps on already loaded files
     int load(const wcstring &cmd, bool reload);
 
-    // Check whether we have tried loading the given command. Does not do any I/O.
+    /// Check whether we have tried loading the given command. Does not do any I/O.
     bool has_tried_loading(const wcstring &cmd);
 
-    // Tell the autoloader that the specified file, in the specified path, is no longer loaded.
-    //
-    // \param cmd the filename to search for. The suffix '.fish' is always added to this name
-    // \param on_unload a callback function which will be called before (re)loading a file, may be
-    // used to unload the previous file.
-    // \return non-zero if the file was removed, zero if the file had not yet been loaded
+    /// Tell the autoloader that the specified file, in the specified path, is no longer loaded.
+    /// Returns non-zero if the file was removed, zero if the file had not yet been loaded
     int unload(const wcstring &cmd);
 
-    // Check whether the given command could be loaded, but do not load it.
+    /// Check whether the given command could be loaded, but do not load it.
     bool can_load(const wcstring &cmd, const env_vars_snapshot_t &vars);
 };
 #endif
diff --git a/src/wcstringutil.h b/src/wcstringutil.h
index ea4489e7..4a86f86e 100644
--- a/src/wcstringutil.h
+++ b/src/wcstringutil.h
@@ -7,18 +7,16 @@
 
 #include "common.h"
 
-/// Typedef that represents a range in a wcstring. The first element is the location, the second is
-/// the count.
+/// @typedef wcstring_range represents a range in a wcstring.
+/// The first element is the location, the second is the count.
 typedef std::pair<wcstring::size_type, wcstring::size_type> wcstring_range;
 
 /// wcstring equivalent of wcstok(). Supports NUL. For convenience and wcstok() compatibility, the
 /// first character of each token separator is replaced with NUL.
-///
-/// Returns a pair of (pos, count).
-/// Returns (npos, npos) when it's done.
-/// Returns (pos, npos) when the token is already known to be the final token.
-///
-/// Note that the final token may not necessarily return (pos, npos).
+/// @return Returns a pair of (pos, count).
+///         This will be (npos, npos) when it's done. In the form of (pos, npos)
+///         when the token is already known to be the final token.
+/// @note The final token may not necessarily return (pos, npos).
 wcstring_range wcstring_tok(wcstring& str, const wcstring& needle,
                             wcstring_range last = wcstring_range(0, 0));