meta: Update all of the heading comments in apps/

apps/about.c

@@ -1,13 +1,14 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018-2019 K. Lange
- *
- * about - Show an "About <Application>" dialog.
+/**
+ * @brief about - Show an "About <Application>" dialog.
  *
  * By default, shows "About ToaruOS", suitable for use as an application
  * menu entry. Optionally, takes arguments specifying another application
  * to describe, suitable for the "Help > About" menu bar entry.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018-2019 K. Lange
  */
 #include <toaru/yutani.h>
 #include <toaru/graphics.h>

apps/basename.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief basename - print file name
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * basename - print file name
  */
 #include <stdio.h>
 #include <string.h>

apps/beep.c

@@ -1,4 +1,11 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Implementation of the 'beep' utility.
+ *
+ * I've tried to get the functionality here as close to the common
+ * utility available on Linux systems so that "beep music" can be
+ * played back.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2014-2018 K. Lange

apps/block-dev-stats.c

@@ -1,3 +1,13 @@
+/**
+ * @brief Show block device statistics, where available.
+ *
+ * Shows cache hit/miss/write counts for ATA devices, mostly.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
+ */
 #include <stdio.h>
 #include <unistd.h>
 #include <fcntl.h>

apps/cal.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief cal - print a calendar
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2019 K. Lange
- *
- * cal - print a calendar
  */
 #include <stdio.h>
 #include <string.h>

apps/cat-img.c

@@ -1,4 +1,7 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Display images in a Toaru terminal.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2016-2018 K. Lange

apps/cat.c

@@ -1,14 +1,15 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2018 K. Lange
- *
- * cat - Concatenate files
+/**
+ * @brief cat - Concatenate files
  *
  * Concatenates files together to standard output.
  * In a supporting terminal, you can then pipe
  * standard out to another file or other useful
  * things like that.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013-2018 K. Lange
  */
 #include <stdio.h>
 #include <fcntl.h>

apps/chmod.c

@@ -1,13 +1,14 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief chmod - change file permissions
+ *
+ * This implementation is likely non-compliant, though it does
+ * attempt to look similar to the standard POSIX syntax,
+ * supporting both octal mode setings and +/-rwx flavors.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * chmod - change file permissions
- *
- * Note: This implementation is likely non-compliant, though it does
- *       attempt to look similar to the standard POSIX syntax,
- *       supporting both octal mode setings and +/-rwx flavors.
  */
 #include <unistd.h>
 #include <stdio.h>

apps/chown.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief chown - bad implementation thereof
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * chown - bad implementation thereof
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/clear.c

@@ -1,14 +1,15 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013 K. Lange
- *
- * clear - Clear the terminal
+/**
+ * @brief clear - Clear the terminal
  *
  * Sends an escape code to clear the screen. Ideally, this should
  * come from a database of terminal escape codes (eg. terminfo),
  * but we don't have one of those yet, so just send a code that
  * makes sense for a lot of terminals.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013 K. Lange
  */
 #include <stdio.h>
 

apps/compositor.c

@@ -1,9 +1,5 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2018 K. Lange
- *
- * Yutani - The ToaruOS Compositor.
+/**
+ * @brief Yutani - The ToaruOS Window Compositor.
  *
  * Yutani is a canvas-based window compositor and manager.
  * It employs shared memory to provide clients access to
@@ -13,6 +9,11 @@
  * to client events, etc., as well as to communicate requests from
  * the client to the server, such as creation of new windows,
  * movement, resizing, and display updates.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013-2018 K. Lange
  */
 #include <stdio.h>
 #include <stdint.h>

apps/cp.c

@@ -1,10 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief cp - Copy files
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * cp - Copy files
- *
  */
 #include <string.h>
 #include <stdio.h>

apps/cpuwidget.c

@@ -1,4 +1,10 @@
-/*
+/**
+ * @brief System monitor tool
+ *
+ * Displays CPU usage, memory usage, and network usage, with nice
+ * curvy anti-aliased graphs that scroll smoothly.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2021 K. Lange

apps/crc32.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * crc32 - Simple CRC32 calculator for verifying file integrity.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * crc32 - Simple CRC32 calculator for verifying file integrity.
  */
 #include <stdio.h>
 #include <errno.h>

apps/cursor-off.c

@@ -1,15 +1,16 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2016-2018 K. Lange
- *
- * cursor-off - Disables the VGA text mode cursor.
+/**
+ * @brief cursor-off - Disables the VGA text mode cursor.
  *
  * This is an old tool that calls a special system call
  * to change the VGA text-mode cursor position. The VGA
  * terminal renders its own cursor in software, so we
  * try to move the hardware cursor off screen so it doesn't
  * interfere with the rest of the terminal and look weird.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2016-2018 K. Lange
  */
 #include <unistd.h>
 #include <fcntl.h>

apps/date.c

@@ -1,8 +1,4 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
+/**
  * date - Print the current date and time.
  *
  * TODO: The traditional POSIX version of this tool is supposed
@@ -12,6 +8,11 @@
  *
  *       At the very least, improving this to print the "correct"
  *       default format would be good.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 #include <stdio.h>
 #include <time.h>

apps/demo.c

@@ -1,3 +1,11 @@
+/**
+ * @brief Simple executable that was used during initial testing of Misaka.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
+ */
 #include <stdio.h>
 
 int main(int argc, char * argv[]) {

apps/dhclient.c

@@ -1,3 +1,11 @@
+/**
+ * @brief DHCP client
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
+ */
 #include <stdint.h>
 #include <stdio.h>
 #include <string.h>

apps/dirname.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief dirname - print directory name from path string
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * dirname - print directory name from path string
  */
 #include <stdio.h>
 #include <string.h>

apps/drawlines.c

@@ -1,18 +1,15 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2018 K. Lange
- *
- * drawlines - Draw random lines into a GUI window
+/**
+ * @brief drawlines - Draw random lines into a GUI window
  *
  * The original compositor demo application, this dates all the
  * way back to the original pre-Yutani compositor. Opens a very
  * basic window (no decorations) and randomly fills it with
- * colorful lines in a separate thread from the listener.
+ * colorful lines.
  *
- * There's no good reason for this to use threads - it should use
- * `fswait2` to apply timeouts - but it demonstrates threading
- * so we'll leave it that way for now.
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013-2021 K. Lange
  */
 #include <stdlib.h>
 #include <assert.h>

apps/du.c

@@ -1,12 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * du - calculate file size usage
+/**
+ * @brief du - calculate file size usage
  *
  * TODO: Should use st_blocks, but we don't set that in the kernel yet?
  *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 #include <stdio.h>
 #include <string.h>

apps/echo.c

@@ -1,12 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2018 K. Lange
- *
- * echo - Print arguments to stdout.
+/**
+ * @brief echo - Print arguments to stdout.
  *
  * Prints arguments to stdout, possibly interpreting escape
  * sequences in the arguments.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013-2018 K. Lange
  */
 #include <ctype.h>
 #include <stdio.h>

apps/env.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief env - Print or set environment
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2018 K. Lange
- *
- * env - Print or set environment
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/false.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief false - returns a failure status code.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * false - returns a failure status code.
  */
 int main() {
 	return 1;

apps/fgrep.c

@@ -1,12 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2014-2018 K. Lange
- *
- * fgrep - dump grep
+/**
+ * @brief fgrep - dump grep
  *
  * Locates strings in files and prints the lines containing them,
  * with extra color identification if stdout is a tty.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2014-2018 K. Lange
  */
 #include <stdio.h>
 #include <fcntl.h>

apps/find-timezone.c

@@ -1,3 +1,13 @@
+/**
+ * @brief Query a remote API to get timezone information based geoip lookup.
+ *
+ * We ask @see ip-api.com for geo-ip data, which includes a timezone offset.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
+ */
 #include <stdio.h>
 #include <stdlib.h>
 #include <math.h>

apps/font-preview.c

@@ -1,5 +1,10 @@
 /**
  * @brief TrueType font previewer
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
  */
 #include <stdio.h>
 #include <stdint.h>

apps/free.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief free - Show free / used / total RAM
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2015-2018 K. Lange
- *
- * free - Show free / used / total RAM
  */
 #include <stdio.h>
 #include <string.h>

apps/getty.c

@@ -1,12 +1,16 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * getty - Manage a TTY.
+/**
+ * @brief getty - Manage a TTY.
  *
  * Wraps a serial port (or other dumb connection) with a pty
  * and manages a login for it.
+ *
+ * This is not really what 'getty' should do - see @ref login-loop.c
+ * for something more akin to the "getty" on other platforms.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/glogin-provider.c

@@ -1,13 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Graphical login display.
+ *
+ * Called by @ref glogin to show a graphical login prompt.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2015 K. Lange
  */
-/*
- * glogin
- *
- * Graphical Login screen
- */
 #include <stdlib.h>
 #include <assert.h>
 #include <unistd.h>

apps/glogin.c

@@ -1,12 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2015 K. Lange
- *
- * Graphical login daemon.
+/**
+ * @brief Graphical login daemon.
  *
  * Launches graphical login windows and manages login sessions.
  *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013-2015 K. Lange
  */
 #include <stdlib.h>
 #include <assert.h>

apps/gsudo.c

@@ -1,12 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2014-2017 K. Lange
- *
- * gsudo - graphical implementation of sudo
+/**
+ * @brief gsudo - graphical implementation of sudo
  *
  * probably even less secure than the original
  *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2014-2017 K. Lange
  */
 
 #include <stdio.h>

apps/gunzip.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief gunzip - decompress gzip-compressed payloads
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2020 K. Lange
- *
- * gunzip - decompress gzip-compressed payloads
  */
 #include <stdio.h>
 #include <stdint.h>

apps/head.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief head - Print the first `n` lines of a file.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * head - Print the first `n` lines of a file.
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/hello.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief hello - Prints "Hello, world."
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2011~2018 K. Lange
- *
- * hello - Prints "Hello, world."
  */
 #include <stdio.h>
 

apps/help-browser.c

@@ -1,15 +1,16 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018-2020 K. Lange
- *
- * help-browser - Display documentation.
+/**
+ * @brief help-browser - Display documentation.
  *
  * This is a work-in-progress reimplementation of the help browser
  * from mainline ToaruOS. It is currently incomplete.
  *
  * Eventually, this should be a rich text document browser, almost
  * akin to a web browser. Right now it just says "Hello, world."
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018-2020 K. Lange
  */
 #include <stdio.h>
 #include <unistd.h>

apps/hexify.c

@@ -1,12 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief hexify - Convert binary to hex.
+ *
+ * This is based on the output of xxd.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * hexify - Convert binary to hex.
- *
- * This is based on the output of xxd.
- * Does NOT a hex-to-bin option - something to consider.
  */
 #include <stdio.h>
 #include <ctype.h>

apps/hostname.c

@@ -1,11 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief hostname - Prints or sets the system hostname.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2018 K. Lange
- *
- * hostname
- *
- * Prints or sets the system hostname.
  */
 #include <stdio.h>
 #include <unistd.h>

apps/ifconfig.c

@@ -5,6 +5,11 @@
  * Manipulates and enumerates network interfaces.
  *
  * All of the APIs used in this tool are temporary and subject to change.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
  */
 #include <stdio.h>
 #include <stdint.h>

apps/imgviewer.c

@@ -1,9 +1,5 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * imgviewer - Display bitmaps in a graphical window.
+/**
+ * @brief imgviewer - Display bitmaps in a graphical window.
  *
  * This is probably the 4th time I've (re)written a version of
  * this application... This uses the libtoaru_graphics sprite
@@ -11,6 +7,10 @@
  * that ends up supporting - which at the time of writing is
  * just bitmaps of various types.
  *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 
 #include <stdio.h>

apps/init.c

@@ -1,9 +1,5 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * init - First process.
+/**
+ * @brief init - First process.
  *
  * `init` calls startup scripts and then waits for them to complete.
  * It also waits for orphaned proceses so they can be collected.
@@ -28,6 +24,11 @@
  * exit so that the rest of the startup process can continue.
  *
  * When the last startup script finishes, `init` will reboot the system.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 
 #include <dirent.h>

apps/insmod.c

@@ -1,10 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief insmod - Load kernel module
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2016 K. Lange
- *
- * insmod - Load kernel module
- *
  */
 #include <stdio.h>
 #include <errno.h>

apps/irc.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief irc - Internet Relay Chat client
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * irc - Internet Relay Chat client
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/json-test.c

@@ -1,3 +1,11 @@
+/**
+ * @brief Test suite for the JSON library.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2019-2020 K. Lange
+ */
 #include <stdio.h>
 #include <stdlib.h>
 #include <math.h>

apps/julia.c

@@ -1,14 +1,14 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief julia - Julia Fractal Generator
+ *
+ * Displays Julia fractals in a window. Use the keyboard
+ * to navigate, switch palettes, and change parameters.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2018 K. Lange
- *
- * julia - Julia Fractal Generator
- *
- * This is the updated windowed version of the
- * julia fractal generator demo.
+ * Copyright (C) 2013-2021 K. Lange
  */
-
 #include <stdio.h>
 #include <stdint.h>
 #include <string.h>

apps/kbd-test.c

@@ -1,3 +1,15 @@
+/**
+ * @brief Keyboard test tool
+ *
+ * XXX This probably doesn't work anymore. It uses the VGA text mode
+ *     region but it doesn't map it; legacy interfaces in toaru32
+ *     just mapped this accessible to userspace...
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
+ */
 #include <stdio.h>
 #include <fcntl.h>
 #include <unistd.h>

apps/kcmdline.c

@@ -1,9 +1,5 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * kcmdline - Parse /proc/cmdline usefully.
+/**
+ * @brief kcmdline - Parse /proc/cmdline usefully.
  *
  * Parses /proc/cmdline and provides an interface for querying
  * whether an argument was present, and its value if applicable.
@@ -15,6 +11,11 @@
  *
  * TODO: This should probably be a library we can use in other
  *       applications...
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/kdebug.c

@@ -1,20 +0,0 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2014-2018 K. Lange
- *
- * kdebug - Launch kernel shell
- */
-#include <errno.h>
-#include <stdlib.h>
-#include <sys/wait.h>
-#include <sys/sysfunc.h>
-
-int main(int argc, char * argv[]) {
-	sysfunc(TOARU_SYS_FUNC_KDEBUG, NULL);
-	int status;
-	while (wait(&status)) {
-		if (errno == ECHILD) break;
-	}
-	return WEXITSTATUS(status);
-}

apps/kill.c

@@ -1,11 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief kill - Send a signal to a process
+ *
+ * Supports signal names like any mature `kill` should.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2018 K. Lange
- *
- * kill - Send a signal to a process
- *
- * Supports signal names like any mature `kill` should.
  */
 #include <stdio.h>
 #include <string.h>

apps/killall.c

@@ -1,11 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief killall - Send signals to processes matching name
+ *
+ * Find processes by name and send them signals.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * killall - Send signals to processes matching name
- *
- * Find processes by name and send them signals.
  */
 #include <fcntl.h>
 #include <stdint.h>

apps/live-session.c

@@ -1,12 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * live-session - Run live CD user session.
+/**
+ * @brief live-session - Run live CD user session.
  *
  * Launches the general session manager as 'local', waits for the
  * session to end, then launches the login manager.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/ln.c

@@ -1,4 +1,7 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Make symlinks
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2015 Mike Gerow

apps/login.c

@@ -1,12 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2014 K. Lange
- *
- * Login Service
+/**
+ * @brief TTY login prompt
  *
  * Provides the user with a login prompt and starts their session.
  *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013-2014 K. Lange
  */
 
 #include <stdio.h>

apps/logname.c

@@ -1,10 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Display the user's name, as returned by getlogin()
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * logname - Effectively the same as whoami, but for compliance
- *           with POSIX, this uses getlogin().
  */
 #include <unistd.h>
 #include <stdio.h>

apps/ls.c

@@ -1,15 +1,14 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2018 K. Lange
- *
- * ls
+/**
+ * @brief List files
  *
  * Lists files in a directory, with nice color
  * output like any modern ls should have.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013-2018 K. Lange
  */
-
-
 #include <fcntl.h>
 #include <stdint.h>
 #include <stdio.h>

apps/lspci.c

@@ -1,10 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * lspci - Print information about connected PCI devices.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * lspci - Print information about connected PCI devices.
- *
  */
 #include <stdio.h>
 #include <unistd.h>

apps/migrate.c

@@ -1,9 +1,5 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * migrate - Relocate root filesystem to tmpfs
+/**
+ * @brief migrate - Relocate root filesystem to tmpfs
  *
  * Run as part of system startup to move the ext2 root ramdisk
  * into a flexible in-memory temporary filesystem, which allows
@@ -11,6 +7,11 @@
  * the ext2 driver against the static in-memory ramdisk.
  *
  * Based on the original Python implementation.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 #include <string.h>
 #include <stdio.h>

apps/misaka-test.c

@@ -1,6 +1,10 @@
 /**
- * @file  misaka-test.c
+ * @file  apps/misaka-test.c
  * @brief Test app for Misaka with a bunch of random stuff.
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/mixerctl.c

@@ -1,4 +1,7 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Control audio mixer knobs
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2015 Mike Gerow

apps/mkdir.c

@@ -1,11 +1,10 @@
-/* vim:tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Create directories
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2014 K. Lange
- *
- * mkdir
- *
- * Create a directory.
  */
 #include <stdio.h>
 #include <stdint.h>

apps/mktemp.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief mktemp - create a temporary directory and print its name
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * mktemp - create a temporary directory and print its name
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/more.c

@@ -1,3 +1,11 @@
+/**
+ * @brief Print piped input or files one screenful at a time.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2014-2018 K. Lange
+ */
 #include <errno.h>
 #include <stdint.h>
 #include <stdio.h>

apps/mount.c

@@ -1,11 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Mount filesystems into the VFS
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2014-2018 K. Lange
- *
- * mount
- *
- * Mount a filesystem.
  */
 
 #include <stdio.h>

apps/msk.c

@@ -1,9 +1,5 @@
-/* vim: ts=4 sw=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * msk - Package Management Utility for ToaruOS
+/**
+ * @brief Package Management Utility for ToaruOS
  *
  * This is a not-quite-faithful reconstruction of the original
  * Python msk. The supported package format is a bit different,
@@ -11,6 +7,11 @@
  *
  * Packages can optionally be uncompressed, which is also
  * important for bootstrapping at the moment.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 #include <stdio.h>
 #include <string.h>

apps/mv.c

@@ -1,11 +1,15 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Move files
+ *
+ * Poor implementation, mostly just 'cp' and 'rm'.
+ *
+ * Ideally, should figure out if it can use 'rename'... and also
+ * we should implement 'rename'...
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * DUMMY mv implementation that calls cp + rm
- *
- * TODO: Actually implement the plumbing for mv!
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/nproc.c

@@ -4,7 +4,7 @@
  * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
+ * Copyright (C) 2021 K. Lange
  */
 #include <stdio.h>
 #include <sys/sysfunc.h>

apps/nslookup.c

@@ -1,10 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Perform DNS lookups.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2016-2018 K. Lange
- *
- * nslookup - perform nameserver lookups
- *
  */
 #include <stdio.h>
 #include <stdint.h>

apps/package-manager.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Graphical interface to msk
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * package-manager - Graphical interface to msk
+ * Copyright (C) 2018-2021 K. Lange
  */
 #include <stdio.h>
 #include <unistd.h>

apps/piano.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief piano - Interactively make beeping noises
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2014-2018 K. Lange
- *
- * piano - Interactively make beeping noises
  */
 #include <stdio.h>
 #include <unistd.h>

apps/pidof.c

@@ -1,10 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Look up the PIDs of all processes with a particular name
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * pidof - Find and print process IDs
- *
  */
 #include <sys/stat.h>
 #include <fcntl.h>

apps/plasma.c

@@ -1,10 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Threaded graphical demo that draws animated plasma.
+ *
+ * Good for burning CPU.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2018 K. Lange
- *
- * plasma - Draw animated plasma in a window
- *
  */
 #include <stdlib.h>
 #include <assert.h>

apps/play.c

@@ -1,12 +1,16 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2015-2018 K. Lange
- *
- * play - Play back PCM samples
+/**
+ * @brief play - Play back PCM samples
  *
  * This needs very specifically-formatted PCM data to function
  * properly - 16-bit, signed, stereo, little endian, and 48KHz.
+ *
+ * TODO This should be fixed up to play back WAV files properly.
+ *      We have a sample rate convert in the out-of-repo playmp3
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2015-2018 K. Lange
  */
 
 #include <stdio.h>

apps/polygons.c

@@ -1,5 +1,16 @@
 /**
  * @brief Draw filled polygons from line segments.
+ *
+ * This is an older version of the polygon rasterizer that turned
+ * into the TrueType gylph rasterizer. Still makes for a neat
+ * little graphical demo. Should probably be updated to use
+ * the glyph rasterization code instead of its own oudated
+ * copy though...
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
  */
 
 #include <stdio.h>

apps/pong.c

@@ -1,9 +1,5 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2015 K. Lange
- *
- * pong - Window Manager Pong
+/**
+ * @brief pong - Window Manager Pong
  *
  * Play pong where the paddles and ball are all windows.
  * Use the WM bindings to drag the left paddle to play.
@@ -16,6 +12,10 @@
  * position, and window moves for the ball and other paddle keep
  * things in the right place visually.
  *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2015 K. Lange
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/ps.c

@@ -1,14 +1,16 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Print a list of running processes.
+ *
+ * The listed processes are limited to ones owned by the current
+ * user and are listed in PID order. Various options allow for
+ * threads to be shown separately, extra information to be
+ * included in the output, etc.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2018 K. Lange
- *
- * ps
- *
- * print a list of running processes
+ * Copyright (C) 2013-2021 K. Lange
  */
-
-
 #include <sys/stat.h>
 #include <fcntl.h>
 #include <stdint.h>

apps/pstree.c

@@ -1,10 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief pstree - Display a tree of running process
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2014-2018 K. Lange
- *
- * pstree - Display a tree of running process
- *
  */
 #include <sys/stat.h>
 #include <fcntl.h>

apps/pwd.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Print the current working directory
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * pwd - Print working directory
  */
 #include <unistd.h>
 #include <stdio.h>

apps/qemu-display-hack.c

@@ -1,17 +1,18 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
+/**
+ * @brief qemu-display-hack - Manage display size under QEMU
  *
- * qemu-display-hack - Manage display size under QEMU
+ * XXX Does this still work? Does the TTY interface interfere
+ *     with the operation of the communication pipe?
  *
  * Communicates with a harness on the host running QEMU to
  * automatically update the display resolution when the
  * QEMU window size changes, similar to how VirtualBox's
  * display size changing works.
  *
- * This is automatically run at startup if the harness is
- * detected by the 90_qemu_hack.sh startup script.
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/qemu-fwcfg.c

@@ -1,13 +1,14 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * qemu-fwcfg - Read QEMU fwcfg values.
+/**
+ * @brief qemu-fwcfg - Read QEMU fwcfg values.
  *
  * Provides easy access to values and files set by QEMU's -fw_cfg
  * flag. This is used by the QEMU harness, as well as the bootloader,
  * and can be used to provide files directly to the guest.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2018 K. Lange
  */
 
 #include <stdio.h>

apps/readelf.c

@@ -3,6 +3,17 @@
  * @brief Display information about a 64-bit Elf binary or object.
  *
  * Implementation of a `readelf` utility.
+ *
+ * I've tried to get the output here as close to the binutils format
+ * as possible, so it should be compatible with tools that try to
+ * parse that. Most of the same arguments should also be supported.
+ *
+ * This is a rewrite of an earlier version.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2020-2021 K. Lange
  */
 #include <stdio.h>
 #include <string.h>

apps/readlink.c

@@ -1,4 +1,7 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Examine symlinks and print the path they point to.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2015 Mike Gerow

apps/reboot.c

@@ -1,10 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief (Try to) reboot the system.
+ *
+ * Note that only root can syscall_reboot, and this doesn't
+ * do any fancy setuid stuff.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2014 K. Lange
- *
- * reboot - Reboot the system
- *
  */
 #include <stdio.h>
 #include <syscall.h>

apps/reset.c

@@ -1,9 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief reset - make the terminal sane, and clear it
+ *
+ * Also clears scrollback!
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2018 K. Lange
- *
- * reset - make the terminal sane, and clear it
+ * Copyright (C) 2018-2021 K. Lange
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/rm.c

@@ -1,11 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief rm - Unlink files
+ *
+ * TODO: Support recursive, directory removal, etc.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2018 K. Lange
- *
- * rm - Unlink files
- *
- * TODO: Support recursive, directory removal, etc.
  */
 #include <stdio.h>
 #include <string.h>

apps/serial-console.c

@@ -1,12 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief serial console
+ *
+ * Old tool for poking serial ports. Probably doesn't work right
+ * anymore since serial ports are now behind PTYs.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2014 K. Lange
- *
- * serial console
- *
- * Runs a dumb console on a serial port or something similar.
- *
  */
 #include <stdio.h>
 #include <stdint.h>

apps/session.c

@@ -1,12 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief session - UI session manager
+ *
+ * Runs the user's yutanirc or starts up a panel and desktop
+ * if they don't have one. Generally run by glogin.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * session - UI session manager
- *
- * Runs a background and panel for a single user and waits
- * for them to exit.
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/set-resolution.c

@@ -1,14 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief set-resolution - Change the display resolution.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * set-resolution - Change the display resolution.
- *
- * Simple tool to interface with the IO_VID_SET ioctl.
- *
- * TODO: This is probably something we should request from the
- *       compositor rather than a separate application...
  */
 #include <stdio.h>
 #include <unistd.h>

apps/sh.c

@@ -1,9 +1,5 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
- * This file is part of ToaruOS and is released under the terms
- * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2013-2018 K. Lange
- *
- * E-Shell
+/**
+ * @brief E-Shell
  *
  * This is "experimental shell" - a vaguely-unix-like command
  * interface. It has a very rudimentary parser that understands
@@ -11,8 +7,12 @@
  * handful of built-in commands, including ones that implement
  * some more useful shell syntax such as loops and conditionals.
  * There is support for tab completion of filenames and commands.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2013-2018 K. Lange
  */
-
 #define _XOPEN_SOURCE 500
 #define _POSIX_C_SOURCE 200112L
 #include <stdio.h>

apps/showdialog.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief showdialog - show a window with a dialog prompt with buttons
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * showdialog - show a window with a dialog prompt with buttons
  */
 #include <toaru/yutani.h>
 #include <toaru/graphics.h>

apps/sleep.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief sleep - Do nothing, efficiently.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013 K. Lange
- *
- * sleep - Do nothing, efficiently.
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/snow.c

@@ -1,4 +1,7 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Draw pretty falling snowflakes.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange

apps/sort.c

@@ -1,11 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Sort input lines.
+ *
+ * XXX for reasons unknown this is using its own insertion-sort
+ *     instead of our much nicer quicksort?
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * sort - Sort standard in or files.
- *
- * Currently implemented with a naive insertion sort.
  */
 #include <stdio.h>
 #include <stdlib.h>

apps/splash-log.c

@@ -1,9 +1,27 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Console log manager.
+ *
+ * Presents a PEX endpoint for startup processes to write log
+ * messages to and will only send them to the console if the
+ * debug flag is set or 2 seconds have elapsed since we started.
+ *
+ * This also makes message writes a bit more asynchonrous, which
+ * is useful because the framebuffer console output can be quite
+ * slow and we don't want to slow down start up processes...
+ *
+ * The downside to that is that splash-log may have to play catch-up
+ * and could still be spewing messages to the console after startup
+ * has finished...
+ *
+ * This used to do a lot more work, as it managed both graphical
+ * output of messages and output to the VGA terminal, but that has
+ * all moved back into the kernel's 'fbterm', so now we're just
+ * a message buffer.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018-2021 K. Lange
- *
- * splash-log - Display startup messages before UI has started.
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/stat.c

@@ -1,11 +1,13 @@
-/* vim: ts=4 sw=4 noexpandtab
+/**
+ * @brief Display file status.
+ *
+ * The format for this is terrible and we're missing a bunch
+ * of data we provide in our statbuf...
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013-2018 K. Lange
- *
- * stat
- *
- * Display file status.
  */
 #include <stdio.h>
 #include <stdint.h>

apps/strings.c

@@ -1,9 +1,10 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief strings - print printable character sequences found in a file
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange
- *
- * strings - print printable character sequences found in a file
  */
 #include <stdio.h>
 #include <string.h>

apps/stty.c

@@ -1,4 +1,12 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Set and display tty config bits.
+ *
+ * Surprisingly complete.
+ *
+ * We used to use Minix's stty, so I may have adopted some conventions from it
+ * that aren't in other stty's, but I don't even remember any more.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2018 K. Lange

apps/sudo.c

@@ -1,10 +1,16 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief sudo - Run processes as the root user, after authenticating.
+ *
+ * Our sudo supports cached authentication, so you don't need to keep
+ * entering your password.
+ *
+ * Probably terribly insecure, but our main password auth function is
+ * a plain text comparison, so *shrug*.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2014 K. Lange
- *
- * sudo
- *
  */
 
 #include <stdio.h>

apps/sync.c

@@ -1,3 +1,20 @@
+/**
+ * @brief Wait for filesystem buffered writes to finish.
+ *
+ * And by "wait" and "to finish" I mean "tell the block device
+ * to write everything because it doesn't do that asynchronously".
+ *
+ * Currently only syncs the block device that owns the current
+ * working directory because I haven't set this up to iterate
+ * over mounts yet.
+ *
+ * It will correctly wait until the sync finishes, though.
+ *
+ * @copyright
+ * This file is part of ToaruOS and is released under the terms
+ * of the NCSA / University of Illinois License - see LICENSE.md
+ * Copyright (C) 2021 K. Lange
+ */
 #include <errno.h>
 #include <stdio.h>
 #include <string.h>

apps/sysfunc.c

@@ -1,12 +1,13 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Exceute "extended system function" syscalls.
+ *
+ * Most of these are deprecated, and the ones that are useful
+ * to call manually are all behind other utilities.
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
  * Copyright (C) 2013 K. Lange
- *
- * sysfunc
- *
- * Executes an "extended system function" which
- * is basically just a super-syscall.
  */
 #include <stdlib.h>
 #include <stdio.h>

apps/sysinfo.c

@@ -1,11 +1,31 @@
-/* vim: tabstop=4 shiftwidth=4 noexpandtab
+/**
+ * @brief Display system information.
+ *
+ * Similar to tools like 'screenfetch', this displays information
+ * about ToaruOS, the current machine state, and the user's
+ * configuration options, alongside a terminal-safe rendition
+ * of the OS's logo.
+ *
+ * This is a bit overcomplicated as we used to show an elaborate
+ * logo from a BMP/PNG, but our current logo can be nicely
+ * represented with block characters so that's kind moot; maybe
+ * this should be simplified...
+ *
+ * Uses a few other utilities:
+ *   hostname
+ *   uname -sr
+ *   uptime -p
+ *   msk count
+ *   sh -v
+ *   yutani-query resolution
+ *   font-tool -n
+ *   cpu-name.krk
+ *   free -ut
+ *
+ * @copyright
  * This file is part of ToaruOS and is released under the terms
  * of the NCSA / University of Illinois License - see LICENSE.md
- * Copyright (C) 2015-2018 K. Lange
- *
- * sysinfo - visually based on screenfetch
- *
- * Displays system information in a visually-pleasing format.
+ * Copyright (C) 2015-2021 K. Lange
  */
 #include <stdio.h>
 #include <stdlib.h>