Repair various invalid HeaderDoc comments.

Enable build setting to allow Xcode to complain about invalid
comments.

12 files changed, 43 insertions, 44 deletions

diff --git a/fish.xcodeproj/project.pbxproj b/fish.xcodeproj/project.pbxproj
index 21cd62e4..4234a516 100644
--- a/fish.xcodeproj/project.pbxproj
+++ b/fish.xcodeproj/project.pbxproj
@@ -1547,6 +1547,8 @@
 				ALWAYS_SEARCH_USER_PATHS = NO;
 				CLANG_CXX_LANGUAGE_STANDARD = "c++0x";
 				CLANG_CXX_LIBRARY = "libc++";
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_NULLABLE_TO_NONNULL_CONVERSION = YES;
 				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
 				GCC_ENABLE_CPP_EXCEPTIONS = NO;
@@ -1560,6 +1562,7 @@
 					"DOCDIR=L\\\"/usr/local/share/doc\\\"",
 				);
 				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_MISSING_NEWLINE = YES;
 				GCC_WARN_ABOUT_RETURN_TYPE = YES;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_LABEL = YES;
@@ -1762,6 +1765,8 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_NULLABLE_TO_NONNULL_CONVERSION = YES;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
 				GCC_ENABLE_CPP_EXCEPTIONS = NO;
 				GCC_ENABLE_CPP_RTTI = YES;
@@ -1776,6 +1781,7 @@
 				);
 				GCC_SYMBOLS_PRIVATE_EXTERN = NO;
 				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_MISSING_NEWLINE = YES;
 				GCC_WARN_ABOUT_RETURN_TYPE = YES;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_LABEL = YES;
@@ -1795,6 +1801,8 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_NULLABLE_TO_NONNULL_CONVERSION = YES;
 				DEAD_CODE_STRIPPING = YES;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
 				GCC_ENABLE_CPP_EXCEPTIONS = NO;
@@ -1808,6 +1816,7 @@
 					"DOCDIR=L\\\"/usr/local/share/doc\\\"",
 				);
 				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_MISSING_NEWLINE = YES;
 				GCC_WARN_ABOUT_RETURN_TYPE = YES;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_LABEL = YES;
diff --git a/src/complete.cpp b/src/complete.cpp
index f686ab31..e23e9ce1 100644
--- a/src/complete.cpp
+++ b/src/complete.cpp
@@ -652,8 +652,7 @@ static wcstring complete_function_desc(const wcstring &fn) {
 /// Complete the specified command name. Search for executables in the path, executables defined
 /// using an absolute path, functions, builtins and directories for implicit cd commands.
 ///
-/// \param cmd the command string to find completions for
-/// \param comp the list to add all completions to
+/// \param str_cmd the command string to find completions for
 void completer_t::complete_cmd(const wcstring &str_cmd, bool use_function, bool use_builtin,
                                bool use_command, bool use_implicit_cd) {
     if (str_cmd.empty()) return;
@@ -704,7 +703,7 @@ void completer_t::complete_cmd(const wcstring &str_cmd, bool use_function, bool
 /// \param str The string to complete.
 /// \param args The list of option arguments to be evaluated.
 /// \param desc Description of the completion
-/// \param comp_out The list into which the results will be inserted
+/// \param flags The list into which the results will be inserted
 void completer_t::complete_from_args(const wcstring &str, const wcstring &args,
                                      const wcstring &desc, complete_flags_t flags) {
     bool is_autosuggest = (this->type() == COMPLETE_AUTOSUGGEST);
diff --git a/src/complete.h b/src/complete.h
index 57c743c0..d9203aaf 100644
--- a/src/complete.h
+++ b/src/complete.h
@@ -99,6 +99,13 @@ enum {
 };
 typedef uint32_t completion_request_flags_t;
 
+enum complete_option_type_t {
+    option_type_args_only,    // no option
+    option_type_short,        // -x
+    option_type_single_long,  // -foo
+    option_type_double_long   // --foo
+};
+
 /// Add a completion.
 ///
 /// All supplied values are copied, they should be freed by or otherwise disposed by the caller.
@@ -117,14 +124,12 @@ typedef uint32_t completion_request_flags_t;
 /// complete -c grep -s d -x -a "read skip recurse"
 ///
 /// \param cmd Command to complete.
-/// \param cmd_type If cmd_type is PATH, cmd will be interpreted as the absolute
+/// \param cmd_is_path If cmd_is_path is true, cmd will be interpreted as the absolute
 ///   path of the program (optionally containing wildcards), otherwise it
 ///   will be interpreted as the command name.
-/// \param short_opt The single character name of an option. (-a is a short option,
-///   --all and  -funroll are long options)
-/// \param long_opt The multi character name of an option. (-a is a short option, --all and
-///   -funroll are long options)
-/// \param long_mode Whether to use old style, single dash long options.
+/// \param option The name of an option.
+/// \param option_type The type of option: can be option_type_short (-x),
+///        option_type_single_long (-foo), option_type_double_long (--bar).
 /// \param result_mode Whether to search further completions when this completion has been
 /// succesfully matched. If result_mode is SHARED, any other completions may also be used. If
 /// result_mode is NO_FILES, file completion should not be used, but other completions may be used.
@@ -135,16 +140,12 @@ typedef uint32_t completion_request_flags_t;
 /// \param condition a command to be run to check it this completion should be used. If \c condition
 /// is empty, the completion is always used.
 /// \param flags A set of completion flags
-enum complete_option_type_t {
-    option_type_args_only,    // no option
-    option_type_short,        // -x
-    option_type_single_long,  // -foo
-    option_type_double_long   // --foo
-};
 void complete_add(const wchar_t *cmd, bool cmd_is_path, const wcstring &option,
                   complete_option_type_t option_type, int result_mode, const wchar_t *condition,
                   const wchar_t *comp, const wchar_t *desc, int flags);
 
+
+
 /// Sets whether the completion list for this command is complete. If true, any options not matching
 /// one of the provided options will be flagged as an error by syntax highlighting.
 void complete_set_authoritative(const wchar_t *cmd, bool cmd_type, bool authoritative);
diff --git a/src/exec.cpp b/src/exec.cpp
index aefdbc12..a5bdbc0b 100644
--- a/src/exec.cpp
+++ b/src/exec.cpp
@@ -315,7 +315,7 @@ static bool io_transmogrify(const io_chain_t &in_chain, io_chain_t *out_chain,
 /// \param def the code to evaluate, or the empty string if none
 /// \param node_offset the offset of the node to evalute, or NODE_OFFSET_INVALID
 /// \param block_type the type of block to push on evaluation
-/// \param io the io redirections to be performed on this block
+/// \param ios the io redirections to be performed on this block
 static void internal_exec_helper(parser_t &parser, const wcstring &def, node_offset_t node_offset,
                                  enum block_type_t block_type, const io_chain_t &ios) {
     // If we have a valid node offset, then we must not have a string to execute.
diff --git a/src/expand.h b/src/expand.h
index 7c82d72e..2f1dd2a6 100644
--- a/src/expand.h
+++ b/src/expand.h
@@ -33,7 +33,7 @@ enum {
     /// Don't generate descriptions.
     EXPAND_NO_DESCRIPTIONS = 1 << 6,
     /// Don't expand jobs (but you can still expand processes). This is because
-    // job expansion is not thread safe.
+    /// job expansion is not thread safe.
     EXPAND_SKIP_JOBS = 1 << 7,
     /// Don't expand home directories.
     EXPAND_SKIP_HOME_DIRECTORIES = 1 << 8,
@@ -46,7 +46,7 @@ enum {
     /// working directories.
     EXPAND_SPECIAL_FOR_CD = 1 << 11,
     /// Do expansions specifically to support external command completions. This means using PATH as
-    // a list of potential working directories.
+    /// a list of potential working directories.
     EXPAND_SPECIAL_FOR_COMMAND = 1 << 12
 };
 typedef int expand_flags_t;
@@ -109,7 +109,7 @@ enum expand_error_t {
 ///
 /// \param input The parameter to expand
 /// \param output The list to which the result will be appended.
-/// \param flag Specifies if any expansion pass should be skipped. Legal values are any combination
+/// \param flags Specifies if any expansion pass should be skipped. Legal values are any combination
 /// of EXPAND_SKIP_CMDSUBST EXPAND_SKIP_VARIABLES and EXPAND_SKIP_WILDCARDS
 /// \param errors Resulting errors, or NULL to ignore
 ///
@@ -123,7 +123,7 @@ __warn_unused expand_error_t expand_string(const wcstring &input, std::vector<co
 /// string. This is used for expanding command names.
 ///
 /// \param inout_str The parameter to expand in-place
-/// \param flag Specifies if any expansion pass should be skipped. Legal values are any combination
+/// \param flags Specifies if any expansion pass should be skipped. Legal values are any combination
 /// of EXPAND_SKIP_CMDSUBST EXPAND_SKIP_VARIABLES and EXPAND_SKIP_WILDCARDS
 /// \param errors Resulting errors, or NULL to ignore
 ///
diff --git a/src/highlight.h b/src/highlight.h
index fa62010a..c503e97a 100644
--- a/src/highlight.h
+++ b/src/highlight.h
@@ -69,7 +69,7 @@ struct file_detection_context_t;
 /// Perform syntax highlighting for the shell commands in buff. The result is stored in the color
 /// array as a color_code from the HIGHLIGHT_ enum for each character in buff.
 ///
-/// \param buff The buffer on which to perform syntax highlighting
+/// \param buffstr The buffer on which to perform syntax highlighting
 /// \param color The array in wchich to store the color codes. The first 8 bits are used for fg
 /// color, the next 8 bits for bg color.
 /// \param pos the cursor position. Used for quote matching, etc.
@@ -87,7 +87,7 @@ void highlight_shell_no_io(const wcstring &buffstr, std::vector<highlight_spec_t
 /// highlighted. The result is stored in the color array as a color_code from the HIGHLIGHT_ enum
 /// for each character in buff.
 ///
-/// \param buff The buffer on which to perform syntax highlighting
+/// \param buffstr The buffer on which to perform syntax highlighting
 /// \param color The array in wchich to store the color codes. The first 8 bits are used for fg
 /// color, the next 8 bits for bg color.
 /// \param pos the cursor position. Used for quote matching, etc.
diff --git a/src/pager.cpp b/src/pager.cpp
index 222b510f..d9411362 100644
--- a/src/pager.cpp
+++ b/src/pager.cpp
@@ -143,12 +143,12 @@ line_t pager_t::completion_print_item(const wcstring &prefix, const comp_t *c, s
 /// Print the specified part of the completion list, using the specified column offsets and quoting
 /// style.
 ///
-/// \param l The list of completions to print
 /// \param cols number of columns to print in
-/// \param width An array specifying the width of each column
+/// \param width_per_column An array specifying the width of each column
 /// \param row_start The first row to print
 /// \param row_stop the row after the last row to print
 /// \param prefix The string to print before each completion
+/// \param lst The list of completions to print
 void pager_t::completion_print(size_t cols, int *width_per_column, size_t row_start,
                                size_t row_stop, const wcstring &prefix, const comp_info_list_t &lst,
                                page_rendering_t *rendering) const {
diff --git a/src/parse_util.h b/src/parse_util.h
index 92a1e939..98caaea8 100644
--- a/src/parse_util.h
+++ b/src/parse_util.h
@@ -113,7 +113,7 @@ bool parse_util_argument_is_help(const wchar_t *s, int min_match);
 /// \param quote If not NULL, store the type of quote this parameter has, can be either ', " or \\0,
 /// meaning the string is not quoted.
 /// \param offset If not NULL, get_param will store the offset to the beginning of the parameter.
-/// \param type If not NULL, get_param will store the token type.
+/// \param out_type If not NULL, get_param will store the token type.
 void parse_util_get_parameter_info(const wcstring &cmd, const size_t pos, wchar_t *quote,
                                    size_t *offset, enum token_type *out_type);
 
diff --git a/src/parser.h b/src/parser.h
index d3fd8803..653ca8c6 100644
--- a/src/parser.h
+++ b/src/parser.h
@@ -312,15 +312,6 @@ class parser_t {
     /// parser_t will clean it up.
     profile_item_t *create_profile_item();
 
-    /// Test if the specified string can be parsed, or if more bytes need to be read first. The
-    /// result will have the PARSER_TEST_ERROR bit set if there is a syntax error in the code, and
-    /// the PARSER_TEST_INCOMPLETE bit set if the code contains unclosed blocks.
-    ///
-    /// \param buff the text buffer to test
-    /// \param block_level if non-null, the block nesting level will be filled out into this array
-    /// \param out if non-null, any errors in the command will be filled out into this buffer
-    /// \param prefix the prefix string to prepend to each error message written to the \c out
-    /// buffer.
     void get_backtrace(const wcstring &src, const parse_error_list_t &errors,
                        wcstring *output) const;
 
diff --git a/src/postfork.cpp b/src/postfork.cpp
index 08deb77c..f88934b7 100644
--- a/src/postfork.cpp
+++ b/src/postfork.cpp
@@ -114,7 +114,7 @@ int set_child_group(job_t *j, process_t *p, int print_errors) {
 /// close_unused_internal_pipes() and closing the universal variable server file descriptor. It then
 /// goes on to perform all the redirections described by \c io.
 ///
-/// \param io the list of IO redirections for the child
+/// \param io_chain the list of IO redirections for the child
 ///
 /// \return 0 on sucess, -1 on failure
 static int handle_child_io(const io_chain_t &io_chain) {
diff --git a/src/reader.cpp b/src/reader.cpp
index 968a508a..2d6a6bb8 100644
--- a/src/reader.cpp
+++ b/src/reader.cpp
@@ -1827,14 +1827,15 @@ static void handle_token_history(int forward, int reset) {
     }
 }
 
+
+enum move_word_dir_t { MOVE_DIR_LEFT, MOVE_DIR_RIGHT };
+
 /// Move buffer position one word or erase one word. This function updates both the internal buffer
 /// and the screen. It is used by M-left, M-right and ^W to do block movement or block erase.
 ///
-/// \param dir Direction to move/erase. 0 means move left, 1 means move right.
+/// \param move_right true if moving right
 /// \param erase Whether to erase the characters along the way or only move past them.
-/// \param new if the new kill item should be appended to the previous kill item or not.
-enum move_word_dir_t { MOVE_DIR_LEFT, MOVE_DIR_RIGHT };
-
+/// \param newv if the new kill item should be appended to the previous kill item or not.
 static void move_word(editable_line_t *el, bool move_right, bool erase,
                       enum move_word_style_t style, bool newv) {
     // Return if we are already at the edge.
@@ -2171,11 +2172,9 @@ static int threaded_highlight(background_highlight_context_t *ctx) {
 /// highlighting maykes characters under the sursor unreadable.
 ///
 /// \param match_highlight_pos_adjust the adjustment to the position to use for bracket matching.
-/// This is added to the current cursor position and may be negative.
-/// \param error if non-null, any possible errors in the buffer are further descibed by the strings
-/// inserted into the specified arraylist
+///        This is added to the current cursor position and may be negative.
 /// \param no_io if true, do a highlight that does not perform I/O, synchronously. If false, perform
-/// an asynchronous highlight in the background, which may perform disk I/O.
+///        an asynchronous highlight in the background, which may perform disk I/O.
 static void reader_super_highlight_me_plenty(int match_highlight_pos_adjust, bool no_io) {
     const editable_line_t *el = &data->command_line;
     long match_highlight_pos = (long)el->position + match_highlight_pos_adjust;
diff --git a/src/screen.h b/src/screen.h
index 43e256d1..74cda3be 100644
--- a/src/screen.h
+++ b/src/screen.h
@@ -149,7 +149,7 @@ class screen_t {
 /// \param indent the indent to use for the command line
 /// \param cursor_pos where the cursor is
 /// \param pager_data any pager data, to append to the screen
-/// \param position_is_within_pager whether the position is within the pager line (first line)
+/// \param cursor_is_within_pager whether the position is within the pager line (first line)
 void s_write(screen_t *s, const wcstring &left_prompt, const wcstring &right_prompt,
              const wcstring &commandline, size_t explicit_len, const highlight_spec_t *colors,
              const int *indent, size_t cursor_pos, const page_rendering_t &pager_data,