Fix trivial clang warnings on MSYS2 Windows build

Fix some trivial but fatal warnings generated by clang when run under a
Windows MSYS2 build. Most are `-Wdocumentation` warnings caused by
docstring comments slipping out of sync with the code they document.

Remove unused variable `i_handles` from `sync_pipe_start()` in
`capture/capture_sync.c` to prevent a `-Wunused-but-set` error.

Use `DIAG_OFF(unreachable-code)` in `wsutil/test_wsutil.c` to prevent a
fully-expected `Wunreachable-code` "error" caused by short-circuiting
the function in Windows.

All changes have been confirmed to have no ill effect on a MSVC Windows
build. Changes should not negatively impact other platforms but this has
not been confirmed.

capture/capture_sync.c

@@ -680,7 +680,6 @@ sync_pipe_start(capture_options *capture_opts, GPtrArray *capture_comments,
                 void (*update_cb)(void))
 {
 #ifdef _WIN32
-    size_t i_handles = 0;
     char control_id[ARGV_NUMBER_LEN];
 #endif
     GIOChannel *sync_pipe_read_io;
@@ -838,7 +837,6 @@ sync_pipe_start(capture_options *capture_opts, GPtrArray *capture_comments,
             char *pipe = ws_strdup_printf("%s%" PRIuMAX, EXTCAP_PIPE_PREFIX, (uintmax_t)interface_opts->extcap_pipe_h);
             argv = sync_pipe_add_arg(argv, &argc, pipe);
             g_free(pipe);
-            i_handles++;
 #else
             argv = sync_pipe_add_arg(argv, &argc, interface_opts->extcap_fifo);
 #endif

ui/win32/file_dlg_win32.h

@@ -35,7 +35,8 @@ HANDLE set_thread_per_monitor_v2_awareness(void);
 
 /**
  * @brief revert_thread_per_monitor_v2_awareness
- * @param context
+ * @param context The current thread DPI awareness context, as
+ * returned by set_thread_per_monitor_v2_awareness.
  */
 void revert_thread_per_monitor_v2_awareness(HANDLE context);
 

wsutil/console_win32.h

@@ -54,7 +54,7 @@ WS_DLL_PUBLIC
 bool get_console_wait(void);
 
 /** Set stdin capture.
- * @param console_wait set/no stdin_capture
+ * @param set_stdin_capture whether to enable stdin capture
  */
 WS_DLL_PUBLIC
 void set_stdin_capture(bool set_stdin_capture);

wsutil/test_wsutil.c

@@ -806,6 +806,7 @@ static void test_getopt_opterr1(void)
     int argc;
 
 #ifdef _WIN32
+    DIAG_OFF(unreachable-code)
     g_test_skip("Not supported on Windows");
     return;
 #endif
@@ -845,6 +846,10 @@ static void test_getopt_opterr1(void)
     g_test_trap_subprocess(NULL, 0, 0);
     g_test_trap_assert_passed();
     g_test_trap_assert_stderr(PROGNAME ": unrecognized option: z\n");
+
+#ifdef _WIN32
+    DIAG_ON(unreachable-code)
+#endif
 }
 
 int main(int argc, char **argv)

wsutil/unicode-utils.h

@@ -113,7 +113,7 @@ char * utf_16to8(const wchar_t *utf16str);
  * to be used to normalize command line arguments at program startup.
  *
  * @param argc The number of arguments.
- * @param argv The argument values (vector).
+ * @param wc_argv The argument values (vector).
  */
 WS_DLL_PUBLIC
 char **arg_list_utf_16to8(int argc, wchar_t *wc_argv[]);

wsutil/win32-utils.h

@@ -46,7 +46,7 @@ char * protect_arg (const char *argv);
  * <server> may be "." for localhost. This does not check that a pipe server
  * has actually created the pipe, only that the name is the proper form.
  *
- * @param pipename The UTF-8 string to be checked
+ * @param pipe_name The UTF-8 string to be checked
  * @return TRUE if the string is a valid Windows pipe name.
  */
 WS_DLL_PUBLIC
@@ -89,7 +89,7 @@ const char * win32strexception(DWORD exception);
  * @param current_directory Current directory. Will be converted to its UTF-16 equivalent or NULL.
  * @param startup_info Same as CreateProcess.
  * @param process_information Same as CreateProcess.
- * @return
+ * @return true if process was created successfully.
  */
 WS_DLL_PUBLIC
 BOOL win32_create_process(const char *application_name, const char *command_line,