From 4ec77ba929ed13ed639b803aebb9aa61b1353443 Mon Sep 17 00:00:00 2001
From: Ben Wiederhake <BenWiederhake.GitHub@gmx.de>
Date: Sat, 5 Dec 2020 16:22:58 +0100
Subject: [PATCH] Userland: Write some '--help' descriptions where appropriate

---
 Userland/cal.cpp      | 1 +
 Userland/cat.cpp      | 1 +
 Userland/chgrp.cpp    | 1 +
 Userland/chroot.cpp   | 3 +++
 Userland/copy.cpp     | 1 +
 Userland/crash.cpp    | 3 +++
 Userland/df.cpp       | 1 +
 Userland/disasm.cpp   | 3 +++
 Userland/du.cpp       | 1 +
 Userland/gron.cpp     | 4 +++-
 Userland/head.cpp     | 1 +
 Userland/host.cpp     | 1 +
 Userland/ifconfig.cpp | 1 +
 Userland/jp.cpp       | 1 +
 Userland/js.cpp       | 1 +
 Userland/ls.cpp       | 1 +
 Userland/lsof.cpp     | 3 ++-
 Userland/man.cpp      | 1 +
 Userland/md.cpp       | 1 +
 Userland/nc.cpp       | 1 +
 Userland/open.cpp     | 1 +
 Userland/passwd.cpp   | 1 +
 Userland/paste.cpp    | 4 ++--
 Userland/pro.cpp      | 1 +
 Userland/realpath.cpp | 2 ++
 Userland/strace.cpp   | 2 ++
 Userland/sysctl.cpp   | 2 ++
 Userland/tail.cpp     | 1 +
 Userland/touch.cpp    | 1 +
 Userland/tt.cpp       | 3 +++
 Userland/watch.cpp    | 1 +
 Userland/xargs.cpp    | 1 +
 32 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/Userland/cal.cpp b/Userland/cal.cpp
index 679a42be61b..e2d2f7ca614 100644
--- a/Userland/cal.cpp
+++ b/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);
diff --git a/Userland/cat.cpp b/Userland/cat.cpp
index e9b447c6ece..496eb890bc2 100644
--- a/Userland/cat.cpp
+++ b/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);
 
diff --git a/Userland/chgrp.cpp b/Userland/chgrp.cpp
index cf5885d41c2..18cb0475abf 100644
--- a/Userland/chgrp.cpp
+++ b/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);
diff --git a/Userland/chroot.cpp b/Userland/chroot.cpp
index 36e4daf691b..07c774ecdaa 100644
--- a/Userland/chroot.cpp
+++ b/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);
 
diff --git a/Userland/copy.cpp b/Userland/copy.cpp
index 5319d80273d..d80acd7033f 100644
--- a/Userland/copy.cpp
+++ b/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);
diff --git a/Userland/crash.cpp b/Userland/crash.cpp
index 4f4d96bd87b..227e14a0d45 100644
--- a/Userland/crash.cpp
+++ b/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');
diff --git a/Userland/df.cpp b/Userland/df.cpp
index 9852ff8bf47..d4b1d3cfc80 100644
--- a/Userland/df.cpp
+++ b/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);
 
diff --git a/Userland/disasm.cpp b/Userland/disasm.cpp
index 401086e12a2..6d3a82d0474 100644
--- a/Userland/disasm.cpp
+++ b/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);
 
diff --git a/Userland/du.cpp b/Userland/du.cpp
index bd3daa3d822..fed2898eb43 100644
--- a/Userland/du.cpp
+++ b/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");
diff --git a/Userland/gron.cpp b/Userland/gron.cpp
index 6532af0c25f..0c1b50eca9e 100644
--- a/Userland/gron.cpp
+++ b/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]);
diff --git a/Userland/head.cpp b/Userland/head.cpp
index e6fcfd3b4bc..132df61ee65 100644
--- a/Userland/head.cpp
+++ b/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');
diff --git a/Userland/host.cpp b/Userland/host.cpp
index 6f3bed6fe0b..d77054b8687 100644
--- a/Userland/host.cpp
+++ b/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);
 
diff --git a/Userland/ifconfig.cpp b/Userland/ifconfig.cpp
index a2877632600..2a1b000d9b2 100644
--- a/Userland/ifconfig.cpp
+++ b/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");
diff --git a/Userland/jp.cpp b/Userland/jp.cpp
index 8012ba4f965..d24dac82f6e 100644
--- a/Userland/jp.cpp
+++ b/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);
 
diff --git a/Userland/js.cpp b/Userland/js.cpp
index 112eff03d58..1006bdd171f 100644
--- a/Userland/js.cpp
+++ b/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');
diff --git a/Userland/ls.cpp b/Userland/ls.cpp
index 4c7e607f4c8..76a8c469e98 100644
--- a/Userland/ls.cpp
+++ b/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');
diff --git a/Userland/lsof.cpp b/Userland/lsof.cpp
index e4e387571df..a9bf8800786 100644
--- a/Userland/lsof.cpp
+++ 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");
diff --git a/Userland/man.cpp b/Userland/man.cpp
index 8c53760728b..43e5cc40814 100644
--- a/Userland/man.cpp
+++ b/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");
 
diff --git a/Userland/md.cpp b/Userland/md.cpp
index 5111e12025a..b23c98c206f 100644
--- a/Userland/md.cpp
+++ b/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);
diff --git a/Userland/nc.cpp b/Userland/nc.cpp
index 1f726488f06..8d4f0a76134 100644
--- a/Userland/nc.cpp
+++ b/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');
diff --git a/Userland/open.cpp b/Userland/open.cpp
index c843f3db182..24e73208af7 100644
--- a/Userland/open.cpp
+++ b/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);
 
diff --git a/Userland/passwd.cpp b/Userland/passwd.cpp
index 61cd1e6094e..1b9d4ab1a2f 100644
--- a/Userland/passwd.cpp
+++ b/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');
diff --git a/Userland/paste.cpp b/Userland/paste.cpp
index 57486ae383d..0236fdfc261 100644
--- a/Userland/paste.cpp
+++ b/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 {
diff --git a/Userland/pro.cpp b/Userland/pro.cpp
index d41df71d011..703807a5864 100644
--- a/Userland/pro.cpp
+++ b/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);
diff --git a/Userland/realpath.cpp b/Userland/realpath.cpp
index 1bf4b13542f..328f84a1f75 100644
--- a/Userland/realpath.cpp
+++ b/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);
 
diff --git a/Userland/strace.cpp b/Userland/strace.cpp
index 00bd6fbeecb..c929da66999 100644
--- a/Userland/strace.cpp
+++ b/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);
 
diff --git a/Userland/sysctl.cpp b/Userland/sysctl.cpp
index 764271e6705..74336b6304d 100644
--- a/Userland/sysctl.cpp
+++ b/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);
diff --git a/Userland/tail.cpp b/Userland/tail.cpp
index 9503357e47d..60fb351f192 100644
--- a/Userland/tail.cpp
+++ b/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");
diff --git a/Userland/touch.cpp b/Userland/touch.cpp
index aadea5d60e8..ef6c16162c2 100644
--- a/Userland/touch.cpp
+++ b/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);
 
diff --git a/Userland/tt.cpp b/Userland/tt.cpp
index d1a35144582..6c2fb00a670 100644
--- a/Userland/tt.cpp
+++ b/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);
 
diff --git a/Userland/watch.cpp b/Userland/watch.cpp
index 950de54fed4..8aeccc674b6 100644
--- a/Userland/watch.cpp
+++ b/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');
diff --git a/Userland/xargs.cpp b/Userland/xargs.cpp
index 88628dc4aa1..68e4eb54e35 100644
--- a/Userland/xargs.cpp
+++ 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");