Userland: Write some '--help' descriptions where appropriate

Author: https://github.com/BenWiederhake
Commit: https://github.com/SerenityOS/serenity/commit/4ec77ba929e
Pull-request: https://github.com/SerenityOS/serenity/pull/4332

Userland/cal.cpp

@@ -115,6 +115,7 @@ int main(int argc, char** argv)
     int year = 0;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Display a nice overview of a month or year, defaulting to the current month.");
     // FIXME: This should ensure two values get parsed as month + year
     args_parser.add_positional_argument(day, "Day of year", "day", Core::ArgsParser::Required::No);
     args_parser.add_positional_argument(month, "Month", "month", Core::ArgsParser::Required::No);

Userland/cat.cpp

@@ -45,6 +45,7 @@ int main(int argc, char** argv)
     Vector<const char*> paths;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Concatenate files or pipes to stdout.");
     args_parser.add_positional_argument(paths, "File path", "path", Core::ArgsParser::Required::No);
     args_parser.parse(argc, argv);
 

Userland/chgrp.cpp

@@ -45,6 +45,7 @@ int main(int argc, char** argv)
     const char* path = nullptr;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Change the owning group for a file or directory.");
     args_parser.add_positional_argument(gid_arg, "Group ID", "gid");
     args_parser.add_positional_argument(path, "Path to file", "path");
     args_parser.parse(argc, argv);

Userland/chroot.cpp

@@ -41,6 +41,9 @@ int main(int argc, char** argv)
     const char* userspec = "0:0";
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help(
+        "Run a program in a chroot sandbox. During execution, the program "
+        "sees the given path as '/', and cannot access files outside of it.");
     args_parser.add_positional_argument(path, "New root directory", "path");
     args_parser.add_positional_argument(program, "Program to run", "program", Core::ArgsParser::Required::No);
 

Userland/copy.cpp

@@ -45,6 +45,7 @@ static Options parse_options(int argc, char* argv[])
     Vector<const char*> text;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Copy text from stdin or the command-line to the clipboard.");
     args_parser.add_option(type, "Pick a type", "type", 't', "type");
     args_parser.add_positional_argument(text, "Text to copy", "text", Core::ArgsParser::Required::No);
     args_parser.parse(argc, argv);

Userland/crash.cpp

@@ -125,6 +125,9 @@ int main(int argc, char** argv)
     bool do_read_cpu_counter = false;
 
     auto args_parser = Core::ArgsParser();
+    args_parser.set_general_help(
+        "Exercise error-handling paths of the execution environment "
+        "(i.e., Kernel or UE) by crashing in many different ways.");
     args_parser.add_option(do_all_crash_types, "Test that all of the following crash types crash as expected", nullptr, 'A');
     args_parser.add_option(do_segmentation_violation, "Perform a segmentation violation by dereferencing an invalid pointer", nullptr, 's');
     args_parser.add_option(do_division_by_zero, "Perform a division by zero", nullptr, 'd');

Userland/df.cpp

@@ -53,6 +53,7 @@ struct FileSystem {
 int main(int argc, char** argv)
 {
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Display free disk space of each partition.");
     args_parser.add_option(flag_human_readable, "Print human-readable sizes", "human-readable", 'h');
     args_parser.parse(argc, argv);
 

Userland/disasm.cpp

@@ -42,6 +42,9 @@ int main(int argc, char** argv)
     const char* path = nullptr;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help(
+        "Disassemble an executable, and show human-readable "
+        "assembly code for each function.");
     args_parser.add_positional_argument(path, "Path to i386 binary file", "path");
     args_parser.parse(argc, argv);
 

Userland/du.cpp

@@ -104,6 +104,7 @@ int parse_args(int argc, char** argv, Vector<String>& files, DuOption& du_option
     };
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Display actual or apparent disk usage of files or directories.");
     args_parser.add_option(du_option.all, "Write counts for all files, not just directories", "all", 'a');
     args_parser.add_option(du_option.apparent_size, "Print apparent sizes, rather than disk usage", "apparent-size", 0);
     args_parser.add_option(max_depth, "Print the total for a directory or file only if it is N or fewer levels below the command line argument", "max-depth", 'd', "N");

Userland/gron.cpp

@@ -31,6 +31,7 @@
 #include <AK/StringBuilder.h>
 #include <LibCore/File.h>
 #include <stdio.h>
+#include <string.h>
 
 static bool use_color = false;
 static void print(const String& name, const JsonValue&, Vector<String>& trail);
@@ -58,8 +59,9 @@ int main(int argc, char** argv)
         return 1;
     }
 
-    if (argc != 2) {
+    if (argc != 2 || !strcmp(argv[1], "--help")) {
         fprintf(stderr, "usage: gron <file>\n");
+        fprintf(stderr, "Print each value in a JSON file with its fully expanded key.\n");
         return 0;
     }
     auto file = Core::File::construct(argv[1]);

Userland/head.cpp

@@ -47,6 +47,7 @@ int main(int argc, char** argv)
     Vector<const char*> files;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Print the beginning ('head') of a file.");
     args_parser.add_option(line_count, "Number of lines to print (default 10)", "lines", 'n', "number");
     args_parser.add_option(char_count, "Number of characters to print", "characters", 'c', "number");
     args_parser.add_option(never_print_filenames, "Never print file names", "quiet", 'q');

Userland/host.cpp

@@ -41,6 +41,7 @@ int main(int argc, char** argv)
 
     const char* name_or_ip = nullptr;
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Convert between domain name and IPv4 address.");
     args_parser.add_positional_argument(name_or_ip, "Domain name or IPv4 address", "name");
     args_parser.parse(argc, argv);
 

Userland/ifconfig.cpp

@@ -48,6 +48,7 @@ int main(int argc, char** argv)
     const char* value_mask = nullptr;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Display or modify the configuration of each network interface.");
     args_parser.add_option(value_ipv4, "Set the IP address of the selected network", "ipv4", 'i', "The new IP of the network");
     args_parser.add_option(value_adapter, "Select a specific network adapter to configure", "adapter", 'a', "The name of a network adapter");
     args_parser.add_option(value_gateway, "Set the default gateway of the selected network", "gateway", 'g', "The new IP of the gateway");

Userland/jp.cpp

@@ -51,6 +51,7 @@ int main(int argc, char** argv)
     const char* path = nullptr;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Pretty-print a JSON file with syntax-coloring and indentation.");
     args_parser.add_positional_argument(path, "Path to JSON file", "path");
     args_parser.parse(argc, argv);
 

Userland/js.cpp

@@ -665,6 +665,7 @@ int main(int argc, char** argv)
     const char* script_path = nullptr;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("This is a JavaScript interpreter.");
     args_parser.add_option(s_dump_ast, "Dump the AST", "dump-ast", 'A');
     args_parser.add_option(s_print_last_result, "Print last result", "print-last-result", 'l');
     args_parser.add_option(gc_on_every_allocation, "GC on every allocation", "gc-on-every-allocation", 'g');

Userland/ls.cpp

@@ -101,6 +101,7 @@ int main(int argc, char** argv)
     Vector<const char*> paths;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("List files in a directory.");
     args_parser.add_option(flag_show_dotfiles, "Show dotfiles", "all", 'a');
     args_parser.add_option(flag_show_almost_all_dotfiles, "Do not list implied . and .. directories", nullptr, 'A');
     args_parser.add_option(flag_ignore_backups, "Do not list implied entries ending with ~", "--ignore-backups", 'B');

Userland/lsof.cpp

@@ -146,10 +146,11 @@ int main(int argc, char* argv[])
     pid_t arg_pid { -1 };
     const char* arg_file_name { nullptr };
 
-    Core::ArgsParser parser;
     if (argc == 1)
         arg_all_processes = true;
     else {
+        Core::ArgsParser parser;
+        parser.set_general_help("List open files of a processes. This can mean actual files in the file system, sockets, pipes, etc.");
         parser.add_option(arg_pid, "Select by PID", nullptr, 'p', "pid");
         parser.add_option(arg_fd, "Select by file descriptor", nullptr, 'd', "fd");
         parser.add_option(arg_uid, "Select by login/UID", nullptr, 'u', "login/UID");

Userland/man.cpp

@@ -61,6 +61,7 @@ int main(int argc, char* argv[])
     const char* name = nullptr;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Read manual pages. Try 'man man' to get started.");
     args_parser.add_positional_argument(section, "Section of the man page", "section", Core::ArgsParser::Required::No);
     args_parser.add_positional_argument(name, "Name of the man page", "name");
 

Userland/md.cpp

@@ -47,6 +47,7 @@ int main(int argc, char* argv[])
     int view_width = 0;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Render Markdown to some other format.");
     args_parser.add_option(html, "Render to HTML rather than for the terminal", "html", 'H');
     args_parser.add_option(view_width, "Viewport width for the terminal (defaults to current terminal width)", "view-width", 0, "width");
     args_parser.add_positional_argument(file_name, "Path to Markdown file", "path", Core::ArgsParser::Required::No);

Userland/nc.cpp

@@ -46,6 +46,7 @@ int main(int argc, char** argv)
     int port = 0;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Network cat: Connect to network sockets as if it were a file.");
     args_parser.add_option(should_listen, "Listen instead of connecting", "listen", 'l');
     args_parser.add_option(verbose, "Log everything that's happening", "verbose", 'v');
     args_parser.add_option(should_close, "Close connection after reading stdin to the end", nullptr, 'N');

Userland/open.cpp

@@ -37,6 +37,7 @@ int main(int argc, char* argv[])
     Core::EventLoop loop;
     Vector<const char*> urls_or_paths;
     Core::ArgsParser parser;
+    parser.set_general_help("Open a file or URL by executing the appropriate program.");
     parser.add_positional_argument(urls_or_paths, "URL or file path to open", "url-or-path");
     parser.parse(argc, argv);
 

Userland/passwd.cpp

@@ -62,6 +62,7 @@ int main(int argc, char** argv)
     const char* username = nullptr;
 
     auto args_parser = Core::ArgsParser();
+    args_parser.set_general_help("Modify an account password.");
     args_parser.add_option(del, "Delete password", "delete", 'd');
     args_parser.add_option(lock, "Lock password", "lock", 'l');
     args_parser.add_option(unlock, "Unlock password", "unlock", 'u');

Userland/paste.cpp

@@ -37,6 +37,7 @@ int main(int argc, char* argv[])
     bool no_newline = false;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Paste from the clipboard to stdout.");
     args_parser.add_option(print_type, "Display the copied type", "print-type", 0);
     args_parser.add_option(no_newline, "Do not append a newline", "no-newline", 'n');
     args_parser.parse(argc, argv);
@@ -53,8 +54,7 @@ int main(int argc, char* argv[])
 
     if (!print_type) {
         printf("%s", data_and_type.data.data());
-        // Append a newline to text contents, but
-        // only if we're not asked not to do this.
+        // Append a newline to text contents, unless the caller says otherwise.
         if (data_and_type.mime_type.starts_with("text/") && !no_newline)
             putchar('\n');
     } else {

Userland/pro.cpp

@@ -146,6 +146,7 @@ int main(int argc, char** argv)
     bool save_at_provided_name = false;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Download file from arbitrary ");
     args_parser.add_option(save_at_provided_name, "Write to a file named as the remote file", nullptr, 'O');
     args_parser.add_positional_argument(url_str, "URL to download from", "url");
     args_parser.parse(argc, argv);

Userland/realpath.cpp

@@ -39,6 +39,8 @@ int main(int argc, char** argv)
     const char* path;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help(
+        "Show the 'real' path of a file, by resolving all symbolic links along the way.");
     args_parser.add_positional_argument(path, "Path to resolve", "path");
     args_parser.parse(argc, argv);
 

Userland/strace.cpp

@@ -55,6 +55,8 @@ int main(int argc, char** argv)
     Vector<const char*> child_argv;
 
     Core::ArgsParser parser;
+    parser.set_general_help(
+        "Trace all syscalls and their result.");
     parser.add_option(g_pid, "Trace the given PID", "pid", 'p', "pid");
     parser.add_positional_argument(child_argv, "Arguments to exec", "argument", Core::ArgsParser::Required::No);
 

Userland/sysctl.cpp

@@ -114,6 +114,8 @@ int main(int argc, char** argv)
     const char* var = nullptr;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help(
+        "Show or modify system-internal values. This requires root, and can crash your system.");
     args_parser.add_option(show_all, "Show all variables", nullptr, 'a');
     args_parser.add_positional_argument(var, "Command (var[=value])", "command", Core::ArgsParser::Required::No);
     args_parser.parse(argc, argv);

Userland/tail.cpp

@@ -107,6 +107,7 @@ int main(int argc, char* argv[])
     const char* file = nullptr;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Print the end ('tail') of a file.");
     args_parser.add_option(follow, "Output data as it is written to the file", "follow", 'f');
     args_parser.add_option(line_count, "Fetch the specified number of lines", "lines", 'n', "number");
     args_parser.add_positional_argument(file, "File path", "file");

Userland/touch.cpp

@@ -59,6 +59,7 @@ int main(int argc, char** argv)
     Vector<const char*> paths;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Create a file, or update its mtime (time of last modification).");
     args_parser.add_positional_argument(paths, "Files to touch", "path", Core::ArgsParser::Required::Yes);
     args_parser.parse(argc, argv);
 

Userland/tt.cpp

@@ -44,6 +44,9 @@ int main(int argc, char** argv)
     const char* test_name = "n";
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help(
+        "Exercise error-handling and edge-case paths of the execution environment "
+        "(i.e., Kernel or UE) by doing unusual thread-related things.");
     args_parser.add_positional_argument(test_name, "Test to run (m = mutex, d = detached, p = priority, s = stack size, t = simple thread test, x = set stack, nothing = join race)", "test-name", Core::ArgsParser::Required::No);
     args_parser.parse(argc, argv);
 

Userland/watch.cpp

@@ -121,6 +121,7 @@ int main(int argc, char** argv)
 
     Vector<const char*> command;
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Execute a command repeatedly, and watch its output over time.");
     args_parser.add_option(opt_interval, "Amount of time between updates", "interval", 'n', "seconds");
     args_parser.add_option(flag_noheader, "Turn off the header describing the command and interval", "no-title", 't');
     args_parser.add_option(flag_beep_on_fail, "Beep if the command has a non-zero exit code", "beep", 'b');

Userland/xargs.cpp

@@ -73,6 +73,7 @@ int main(int argc, char** argv)
     int max_bytes_for_one_command = ARG_MAX;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help("Read arguments from stdin and interpret them as command-line arguments for another program. See also: 'man xargs'.");
     args_parser.add_option(placeholder, "Placeholder string to be replaced in arguments", "replace", 'I', "placeholder");
     args_parser.add_option(split_with_nulls, "Split input items with the null character instead of newline", "null", '0');
     args_parser.add_option(specified_delimiter, "Split the input items with the specified character", "delimiter", 'd', "delim");