From bd4622a0d01c7d882c37c46f6730567750dda657 Mon Sep 17 00:00:00 2001 From: Kurtis Rader Date: Tue, 19 Apr 2016 18:17:39 -0700 Subject: make comments Xcode friendly The OS X Xcode IDE has a weird requirement that block comments preceding a function or class definition must begin with three slashes rather than two if you want the comment displayed in the "Quick Help" window. --- src/history.cpp | 102 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 51 insertions(+), 51 deletions(-) (limited to 'src/history.cpp') diff --git a/src/history.cpp b/src/history.cpp index af5d062e..bc9ddd3e 100644 --- a/src/history.cpp +++ b/src/history.cpp @@ -51,9 +51,9 @@ namespace { -// Helper class for certain output. This is basically a string that allows us to ensure we only -// flush at record boundaries, and avoids the copying of ostringstream. Have you ever tried to -// implement your own streambuf? Total insanity. +/// Helper class for certain output. This is basically a string that allows us to ensure we only +/// flush at record boundaries, and avoids the copying of ostringstream. Have you ever tried to +/// implement your own streambuf? Total insanity. class history_output_buffer_t { // A null-terminated C string. std::vector buffer; @@ -64,10 +64,10 @@ class history_output_buffer_t { static size_t safe_strlen(const char *s) { return s ? strlen(s) : 0; } public: - // Add a bit more to HISTORY_OUTPUT_BUFFER_SIZE because we flush once we've exceeded that size. + /// Add a bit more to HISTORY_OUTPUT_BUFFER_SIZE because we flush once we've exceeded that size. history_output_buffer_t() : buffer(HISTORY_OUTPUT_BUFFER_SIZE + 128, '\0'), offset(0) {} - // Append one or more strings. + /// Append one or more strings. void append(const char *s1, const char *s2 = NULL, const char *s3 = NULL) { const char *ptrs[4] = {s1, s2, s3, NULL}; const size_t lengths[4] = {safe_strlen(s1), safe_strlen(s2), safe_strlen(s3), 0}; @@ -95,14 +95,14 @@ class history_output_buffer_t { assert(buffer.at(buffer.size() - 1) == '\0'); } - // Output to a given fd, resetting our buffer. Returns true on success, false on error. + /// Output to a given fd, resetting our buffer. Returns true on success, false on error. bool flush_to_fd(int fd) { bool result = write_loop(fd, &buffer.at(0), offset) >= 0; offset = 0; return result; } - // Return how much data we've accumulated. + /// Return how much data we've accumulated. size_t output_size() const { return offset; } }; @@ -126,7 +126,7 @@ class time_profiler_t { } }; -// Lock a file via fcntl; returns true on success, false on failure. +/// Lock a file via fcntl; returns true on success, false on failure. static bool history_file_lock(int fd, short type) { assert(type == F_RDLCK || type == F_WRLCK); struct flock flk = {}; @@ -136,8 +136,8 @@ static bool history_file_lock(int fd, short type) { return ret != -1; } -// Our LRU cache is used for restricting the amount of history we have, and limiting how long we -// order it. +/// Our LRU cache is used for restricting the amount of history we have, and limiting how long we +/// order it. class history_lru_node_t : public lru_node_t { public: time_t timestamp; @@ -150,13 +150,13 @@ class history_lru_node_t : public lru_node_t { class history_lru_cache_t : public lru_cache_t { protected: - // Override to delete evicted nodes. + /// Override to delete evicted nodes. virtual void node_was_evicted(history_lru_node_t *node) { delete node; } public: explicit history_lru_cache_t(size_t max) : lru_cache_t(max) {} - // Function to add a history item. + /// Function to add a history item. void add_item(const history_item_t &item) { // Skip empty items. if (item.empty()) return; @@ -197,15 +197,15 @@ static history_collection_t histories; static wcstring history_filename(const wcstring &name, const wcstring &suffix); -// Replaces newlines with a literal backslash followed by an n, and replaces backslashes with two -// backslashes. +/// Replaces newlines with a literal backslash followed by an n, and replaces backslashes with two +/// backslashes. static void escape_yaml(std::string *str); -// Inverse of escape_yaml. +/// Inverse of escape_yaml. static void unescape_yaml(std::string *str); -// We can merge two items if they are the same command. We use the more recent timestamp, more -// recent identifier, and the longer list of required paths. +/// We can merge two items if they are the same command. We use the more recent timestamp, more +/// recent identifier, and the longer list of required paths. bool history_item_t::merge(const history_item_t &item) { bool result = false; if (this->contents == item.contents) { @@ -246,7 +246,7 @@ bool history_item_t::matches_search(const wcstring &term, enum history_search_ty } } -// Append our YAML history format to the provided vector at the given offset, updating the offset. +/// Append our YAML history format to the provided vector at the given offset, updating the offset. static void append_yaml_to_buffer(const wcstring &wcmd, time_t timestamp, const path_list_t &required_paths, history_output_buffer_t *buffer) { @@ -270,9 +270,9 @@ static void append_yaml_to_buffer(const wcstring &wcmd, time_t timestamp, } } -// Parse a timestamp line that looks like this: spaces, "when:", spaces, timestamp, newline -// The string is NOT null terminated; however we do know it contains a newline, so stop when we -// reach it +/// Parse a timestamp line that looks like this: spaces, "when:", spaces, timestamp, newline +/// The string is NOT null terminated; however we do know it contains a newline, so stop when we +/// reach it. static bool parse_timestamp(const char *str, time_t *out_when) { const char *cursor = str; // Advance past spaces. @@ -295,8 +295,8 @@ static bool parse_timestamp(const char *str, time_t *out_when) { return false; } -// Returns a pointer to the start of the next line, or NULL. The next line must itself end with a -// newline. Note that the string is not null terminated. +/// Returns a pointer to the start of the next line, or NULL. The next line must itself end with a +/// newline. Note that the string is not null terminated. static const char *next_line(const char *start, size_t length) { // Handle the hopeless case. if (length < 1) return NULL; @@ -323,11 +323,11 @@ static const char *next_line(const char *start, size_t length) { return nextline; } -// Support for iteratively locating the offsets of history items. -// Pass the address and length of a mapped region. -// Pass a pointer to a cursor size_t, initially 0. -// If custoff_timestamp is nonzero, skip items created at or after that timestamp. -// Returns (size_t)(-1) when done. +/// Support for iteratively locating the offsets of history items. +/// Pass the address and length of a mapped region. +/// Pass a pointer to a cursor size_t, initially 0. +/// If custoff_timestamp is nonzero, skip items created at or after that timestamp. +/// Returns (size_t)(-1) when done. static size_t offset_of_next_item_fish_2_0(const char *begin, size_t mmap_length, size_t *inout_cursor, time_t cutoff_timestamp) { size_t cursor = *inout_cursor; @@ -415,8 +415,8 @@ static size_t offset_of_next_item_fish_2_0(const char *begin, size_t mmap_length return result; } -// Same as offset_of_next_item_fish_2_0, but for fish 1.x (pre fishfish). -// Adapted from history_populate_from_mmap in history.c +/// Same as offset_of_next_item_fish_2_0, but for fish 1.x (pre fishfish). +/// Adapted from history_populate_from_mmap in history.c static size_t offset_of_next_item_fish_1_x(const char *begin, size_t mmap_length, size_t *inout_cursor, time_t cutoff_timestamp) { if (mmap_length == 0 || *inout_cursor >= mmap_length) return (size_t)(-1); @@ -456,7 +456,7 @@ static size_t offset_of_next_item_fish_1_x(const char *begin, size_t mmap_length return result; } -// Returns the offset of the next item based on the given history type, or -1. +/// Returns the offset of the next item based on the given history type, or -1. static size_t offset_of_next_item(const char *begin, size_t mmap_length, history_file_type_t mmap_type, size_t *inout_cursor, time_t cutoff_timestamp) { @@ -695,8 +695,8 @@ history_item_t history_t::item_at_index(size_t idx) { return history_item_t(wcstring(), 0); } -// Read one line, stripping off any newline, and updating cursor. Note that our input string is NOT -// null terminated; it's just a memory mapped file. +/// Read one line, stripping off any newline, and updating cursor. Note that our input string is NOT +/// null terminated; it's just a memory mapped file. static size_t read_line(const char *base, size_t cursor, size_t len, std::string &result) { // Locate the newline. assert(cursor <= len); @@ -713,7 +713,7 @@ static size_t read_line(const char *base, size_t cursor, size_t len, std::string } } -// Trims leading spaces in the given string, returning how many there were. +/// Trims leading spaces in the given string, returning how many there were. static size_t trim_leading_spaces(std::string &str) { size_t i = 0, max = str.size(); while (i < max && str[i] == ' ') i++; @@ -738,7 +738,7 @@ static bool extract_prefix_and_unescape_yaml(std::string *key, std::string *valu return where != std::string::npos; } -// Decode an item via the fish 2.0 format. +/// Decode an item via the fish 2.0 format. history_item_t history_t::decode_item_fish_2_0(const char *base, size_t len) { wcstring cmd; time_t when = 0; @@ -812,8 +812,8 @@ history_item_t history_t::decode_item(const char *base, size_t len, history_file } } -// Remove backslashes from all newlines. This makes a string from the history file better formated -// for on screen display. +/// Remove backslashes from all newlines. This makes a string from the history file better formated +/// for on screen display. static wcstring history_unescape_newlines_fish_1_x(const wcstring &in_str) { wcstring out; for (const wchar_t *in = in_str.c_str(); *in; in++) { @@ -828,7 +828,7 @@ static wcstring history_unescape_newlines_fish_1_x(const wcstring &in_str) { return out; } -// Decode an item via the fish 1.x format. Adapted from fish 1.x's item_get(). +/// Decode an item via the fish 1.x format. Adapted from fish 1.x's item_get(). history_item_t history_t::decode_item_fish_1_x(const char *begin, size_t length) { const char *end = begin + length; const char *pos = begin; @@ -901,7 +901,7 @@ history_item_t history_t::decode_item_fish_1_x(const char *begin, size_t length) return history_item_t(out, timestamp); } -// Try to infer the history file type based on inspecting the data. +/// Try to infer the history file type based on inspecting the data. static history_file_type_t infer_file_type(const char *data, size_t len) { history_file_type_t result = history_type_unknown; if (len > 0) { // old fish started with a # @@ -928,8 +928,8 @@ void history_t::populate_from_mmap(void) { } } -// Do a private, read-only map of the entirety of a history file with the given name. Returns true -// if successful. Returns the mapped memory region by reference. +/// Do a private, read-only map of the entirety of a history file with the given name. Returns true +/// if successful. Returns the mapped memory region by reference. bool history_t::map_file(const wcstring &name, const char **out_map_start, size_t *out_map_len, file_id_t *file_id) { bool result = false; @@ -1042,13 +1042,13 @@ bool history_search_t::go_backwards() { return false; } -// Goes to the end (forwards). +/// Goes to the end (forwards). void history_search_t::go_to_end(void) { prev_matches.clear(); } -// Returns if we are at the end, which is where we start. +/// Returns if we are at the end, which is where we start. bool history_search_t::is_at_end(void) const { return prev_matches.empty(); } -// Goes to the beginning (backwards). +/// Goes to the beginning (backwards). void history_search_t::go_to_beginning(void) { // Go backwards as far as we can. while (go_backwards()) @@ -1087,7 +1087,7 @@ static void escape_yaml(std::string *str) { replace_all(str, "\n", "\\n"); // replace newline with backslash + literal n } -// This function is called frequently, so it ought to be fast. +/// This function is called frequently, so it ought to be fast. static void unescape_yaml(std::string *str) { size_t cursor = 0, size = str->size(); while (cursor < size) { @@ -1397,7 +1397,7 @@ bool history_t::save_internal_via_appending() { return ok; } -// Save the specified mode to file; optionally also vacuums. +/// Save the specified mode to file; optionally also vacuums. void history_t::save_internal(bool vacuum) { ASSERT_IS_LOCKED(lock); @@ -1475,9 +1475,9 @@ bool history_t::is_empty(void) { return empty; } -// Populates from older location (in config path, rather than data path) This is accomplished by -// clearing ourselves, and copying the contents of the old history file to the new history file. -// The new contents will automatically be re-mapped later. +/// Populates from older location (in config path, rather than data path) This is accomplished by +/// clearing ourselves, and copying the contents of the old history file to the new history file. +/// The new contents will automatically be re-mapped later. void history_t::populate_from_config_path() { wcstring old_file; if (path_get_config(old_file)) { @@ -1510,7 +1510,7 @@ void history_t::populate_from_config_path() { } } -// Indicate whether we ought to import the bash history file into fish. +/// Indicate whether we ought to import the bash history file into fish. static bool should_import_bash_history_line(const std::string &line) { if (line.empty()) return false; @@ -1717,7 +1717,7 @@ void history_t::add_pending_with_file_detection(const wcstring &str) { } } -// Very simple, just mark that we have no more pending items. +/// Very simple, just mark that we have no more pending items. void history_t::resolve_pending() { scoped_lock locker(lock); this->has_pending_item = false; -- cgit v1.2.3