libos: Document it entirely using Doxygen comments =D

Also, add copyright information to individual files. This is going to be a hassle to do for EVERY file.

.vscode/settings.json

@@ -13,5 +13,16 @@
     "files.trimFinalNewlines": true,
     "files.insertFinalNewline": true,
     "git.inputValidationLength": 72,
-    "git.inputValidationSubjectLength": 72
+    "git.inputValidationSubjectLength": 72,
+    "doxdocgen.file.fileOrder": [
+        "file",
+        "author",
+        "brief",
+        "empty",
+        "copyright",
+        "empty"
+    ],
+    "doxdocgen.file.copyrightTag": [
+        "@copyright Copyright (c) {year}, the Luna authors."
+    ]
 }

libos/include/os/ArgumentParser.h

@@ -1,46 +1,173 @@
+/**
+ * @file ArgumentParser.h
+ * @author apio (cloudapio.eu)
+ * @brief Command-line argument parser.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/StringView.h>
 #include <luna/Vector.h>
 
 namespace os
 {
+    /**
+     * @brief A simple command-line argument parser.
+     */
     class ArgumentParser
     {
       public:
+        /**
+         * @brief Construct a new ArgumentParser object.
+         */
         ArgumentParser();
 
+        /**
+         * @brief Add a description for this command-line utility (shown in the help text).
+         *
+         * @param description The description to use.
+         */
         void add_description(StringView description);
 
-        Result<void> add_positional_argument(StringView& out, StringView name, bool required);
+        /**
+         * @brief Register a new positional argument.
+         *
+         * @param out The variable where the argument's value will be stored.
+         * @param name The positional argument's name.
+         * @param fallback The value to use if the user does not provide one.
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> add_positional_argument(StringView& out, StringView name, StringView fallback);
 
+        /**
+         * @brief Register a new positional argument.
+         *
+         * @param out The variable where the argument's value will be stored.
+         * @param name The positional argument's name.
+         * @param required Whether the user must enter a value for this argument. If this is false and the user does not
+         * enter a value, out will be set to an empty string.
+         * @return Result<void> Whether the operation succeeded.
+         */
+        Result<void> add_positional_argument(StringView& out, StringView name, bool required);
+
+        /**
+         * @brief Register a new switch argument.
+         *
+         * @param out This variable will be set to true if the user provides the switch argument on the command
+         * line.
+         * @param short_flag The short flag to use for this argument, excluding the '-' prefix: an option '-c' would be
+         * passed as 'c'. Can only be a single ASCII character. If you do not wish this argument to have a short flag,
+         * use the space character: ' '.
+         * @param long_flag The long flag to use for this argument, excluding the '--' prefix: an option '--example'
+         * would be passed as 'example'. Can be a string of any length. If you do not wish this argument to have a long
+         * flag, use an empty string: "".
+         * @param help The help text to show for this argument (optional).
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> add_switch_argument(bool& out, char short_flag, StringView long_flag, StringView help = {});
 
-        Result<void> add_value_argument(StringView& out, char short_flag, StringView long_flag, bool value_required,
+        /**
-                                        StringView help = {});
+         * @brief Register a new value argument.
+         *
+         * @param out The variable where the argument's value will be stored.
+         * @param short_flag The short flag to use for this argument, excluding the '-' prefix: an option '-c' would be
+         * passed as 'c'. Can only be a single ASCII character. If you do not wish this argument to have a short flag,
+         * use the space character: ' '.
+         * @param long_flag The long flag to use for this argument, excluding the '--' prefix: an option '--example'
+         * would be passed as 'example'. Can be a string of any length. If you do not wish this argument to have a long
+         * flag, use an empty string: "".
+         * @param fallback The value to use if the user uses the argument but does not provide a value. If, however, the
+         * user does not specify this argument at all, out WILL NOT BE MODIFIED!
+         * @param help The help text to show for this argument (optional).
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> add_value_argument(StringView& out, char short_flag, StringView long_flag, StringView fallback,
                                         StringView help = {});
 
+        /**
+         * @brief Register a new value argument.
+         *
+         * @param out The variable where the argument's value will be stored.
+         * @param short_flag The short flag to use for this argument, excluding the '-' prefix: an option '-c' would be
+         * passed as 'c'. Can only be a single ASCII character. If you do not wish this argument to have a short flag,
+         * use the space character: ' '.
+         * @param long_flag The long flag to use for this argument, excluding the '--' prefix: an option '--example'
+         * would be passed as 'example'. Can be a string of any length. If you do not wish this argument to have a long
+         * flag, use an empty string: "".
+         * @param value_required Whether the user is required to pass a value when using this argument. If this is
+         * false and the user does not enter a value along with the argument, out will be set to an empty string. If,
+         * however, the user does not specify this argument at all, out WILL NOT BE MODIFIED!
+         * @param help The help text to show for this argument (optional).
+         * @return Result<void> Whether the operation succeeded.
+         */
+        Result<void> add_value_argument(StringView& out, char short_flag, StringView long_flag, bool value_required,
+                                        StringView help = {});
+
+        /**
+         * @brief Set the vector to append extra unregistered positional arguments to, after all
+         * registered positional arguments have been parsed. (If no vector is set, these values will instead be
+         * discarded!)
+         *
+         * @param out The vector of StringViews to use.
+         * @param allow_no_more_flags If set, after starting to append values into the vector, no more flags (switch and
+         * value arguments) will be parsed, and will instead be treated as regular positional arguments, as if '--' had
+         * been specified on the command line.
+         */
         void set_vector_argument(Vector<StringView>& out, bool allow_no_more_flags = false);
 
+        /**
+         * @brief Parse the given command-line using this ArgumentParser's registered arguments.
+         *
+         * @param argc The argc value passed to main() or luna_main().
+         * @param argv The argv value passed to main() or luna_main().
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> parse(int argc, char* const* argv);
 
+        /**
+         * @brief A program's copyright and version information.
+         */
         struct ProgramInfo
         {
-            StringView name;
+            StringView name;      // The program's name.
-            StringView version;
+            StringView version;   // The program's version/release.
-            StringView copyright;
+            StringView copyright; // The program's copyright statement.
-            StringView license;
+            StringView license;   // The program's licensing information.
-            StringView authors;
+            StringView authors;   // The program's authors (optional).
-            StringView package;
+            StringView package;   // The package the program is a part of (optional).
         };
 
+        /**
+         * @brief Set this program's copyright and version information (shown in the version text).
+         *
+         * @param info The program information to use.
+         */
         void add_program_info(ProgramInfo info);
 
-        /* Used from programs that are part of the Luna source tree, to add the same version info for all programs.
+        /**
-         * Should not be used otherwise. */
+         * @brief For programs that are part of the Luna source tree, set the version information using Luna's own
+         * version and copyright info and the program name.
+         *
+         * @param name The program name to show in the version information.
+         */
         void add_system_program_info(StringView name);
 
+        /**
+         * @brief Show a short message describing how to find usage information (usually "<program> --help").
+         *
+         * The actual message shown is:
+         *  "Try running '<program> --help' for more information." if --help has not been overridden.
+         *  "Try running '<program> -h' for more information." if -h has not been overridden.
+         *  If both have been overridden, no output is shown.
+         *
+         * Then, the program exits with a non-zero exit code.
+         * This function is designed to be used when the program detects an invalid argument value after parse() has run
+         * successfully.
+         *
+         * @param program_name The program name to show (usually argv[0]).
+         */
         void short_usage(StringView program_name);
 
       private:

libos/include/os/Directory.h

@@ -1,3 +1,12 @@
+/**
+ * @file Directory.h
+ * @author apio (cloudapio.eu)
+ * @brief A C++-friendly API for directory access.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <dirent.h>
 #include <luna/SharedPtr.h>
@@ -7,44 +16,85 @@
 
 namespace os
 {
+    /**
+     * @brief An object-oriented directory handle, which is closed when all references to it go out of scope.
+     */
     class Directory
     {
       public:
+        /**
+         * @brief Create a new Directory object from a path, and open the directory.
+         *
+         * @param path The path to open.
+         * @return Result<SharedPtr<Directory>> A new Directory object.
+         */
         static Result<SharedPtr<Directory>> open(const Path& path);
 
+        /**
+         * @brief A filter to skip certain directory entries.
+         */
         enum class Filter
         {
-            None,
+            None,         // Do not skip anything.
-            Hidden,
+            Hidden,       // Skip all hidden files (that start with a '.' character).
-            ParentAndBase
+            ParentAndBase // Skip only the '.' and '..' entries.
         };
 
+        /**
+         * @brief Read the next entry name from this Directory.
+         *
+         * @param filter The entries to filter out.
+         * @return Result<String> The next entry's name as an owned String object, or an empty string if
+         * there are no more entries.
+         */
         Result<String> next(Filter filter);
 
+        /**
+         * @brief Read the list of entry names from this Directory.
+         *
+         * @param filter The entries to filter out.
+         * @return Result<Vector<String>> The list of entry names.
+         */
         Result<Vector<String>> list_names(Filter filter);
 
+        /**
+         * @brief A directory entry with extra information.
+         */
         struct Entry
         {
-            String name;
+            String name;  // The entry's name.
-            mode_t mode;
+            mode_t mode;  // The entry's file permissions.
-            usize size;
+            usize size;   // The entry's size.
-            time_t mtime;
+            time_t mtime; // The entry's last modification time.
         };
 
+        /**
+         * @brief Read the list of entries from this Directory, fetching extra information for each one.
+         *
+         * @param filter The entries to filter out.
+         * @return Result<Vector<Entry>> The list of entries.
+         */
         Result<Vector<Entry>> list(Filter filter);
 
+        /**
+         * @brief Rewinds this Directory back to the beginning of its entry list.
+         */
         void rewind();
 
+        /**
+         * @brief Returns the file descriptor associated with this Directory.
+         *
+         * @return int The file descriptor.
+         */
         int fd()
         {
             return dirfd(m_dirp);
         }
 
         ~Directory();
-
-      private:
         Directory(Badge<Directory>);
 
+      private:
         DIR* m_dirp { nullptr };
     };
 }

libos/include/os/File.h

@@ -1,5 +1,14 @@
+/**
+ * @file File.h
+ * @author apio (cloudapio.eu)
+ * @brief A C++-friendly API for file access.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
-#include <bits/open-flags.h>
+#include <fcntl.h>
 #include <luna/Buffer.h>
 #include <luna/Result.h>
 #include <luna/SharedPtr.h>
@@ -9,52 +18,160 @@
 
 namespace os
 {
+    /**
+     * @brief An object-oriented file handle, which is closed when all references to it go out of scope.
+     */
     class File
     {
       public:
+        /**
+         * @brief The supported file opening modes.
+         */
         enum OpenMode
         {
-            ReadOnly = O_RDONLY,
+            ReadOnly = O_RDONLY,            // Open the file read-only.
-            WriteOnly = O_WRONLY | O_TRUNC,
+            WriteOnly = O_WRONLY | O_TRUNC, // Open the file write-only, truncating it.
-            ReadWrite = O_RDWR | O_TRUNC,
+            ReadWrite = O_RDWR | O_TRUNC,   // Open the file read-write, truncating it.
-            Append = O_WRONLY | O_APPEND,
+            Append = O_WRONLY | O_APPEND,   // Open the file write-only, and append to it.
-            ReadAppend = O_RDWR | O_APPEND,
+            ReadAppend = O_RDWR | O_APPEND, // Open the file read-write, and append to it.
         };
 
+        /**
+         * @brief Create a new File object from a file path, opening the file.
+         *
+         * @param path The path to open.
+         * @param flags The opening mode to pass to open(2).
+         * @return Result<SharedPtr<File>> A new File object, or ENOENT if the file did not exist.
+         */
         static Result<SharedPtr<File>> open(const Path& path, OpenMode flags);
+
+        /**
+         * @brief Create a new File object from a file path, opening the file or creating it if it does not exist.
+         *
+         * @param path The path to open.
+         * @param flags The opening mode to pass to open(2).
+         * @param mode If a new file is created, the file permissions to apply to it. (default: u=rw,g=r,o=r)
+         * @return Result<SharedPtr<File>> A new File object.
+         */
         static Result<SharedPtr<File>> open_or_create(const Path& path, OpenMode flags, mode_t mode = 0644);
+
+        /**
+         * @brief Create a new File object from a file path, creating the file but erroring out if the file already
+         * exists.
+         *
+         * @param path The path to open.
+         * @param flags The opening mode to pass to open(2).
+         * @param mode The file permissions to apply to the created file. (default: u=rw,g=r,o=r)
+         * @return Result<SharedPtr<File>> A new File object, or EEXIST if the file already existed.
+         */
         static Result<SharedPtr<File>> create(const Path& path, OpenMode flags, mode_t mode = 0644);
 
-        /*
+        /**
-          If path is "-", return standard input (as is common for many CLI apps). Otherwise, open path for reading.
+         * @brief If path is "-", return standard input (as is common for many CLI apps). Otherwise, open path for
-
+         * reading.
-          This function is a convenience function for CLI apps, so that they don't need to check path and open standard
+         *
-          input if necessary.
+         * @param path The path to open.
-        */
+         * @return Result<SharedPtr<File>> A new File object if path was not "-", or the File
+         * object for standard input if path was "-".
+         */
         static Result<SharedPtr<File>> open_input_file(StringView path);
 
+        /**
+         * @brief Returns the File corresponding to standard input.
+         *
+         * @return SharedPtr<File> The File object for standard input.
+         */
         static SharedPtr<File> standard_input();
+
+        /**
+         * @brief Returns the File corresponding to standard output.
+         *
+         * @return SharedPtr<File> The File object for standard output.
+         */
         static SharedPtr<File> standard_output();
+
+        /**
+         * @brief Returns the File corresponding to standard error.
+         *
+         * @return SharedPtr<File> The File object for standard error.
+         */
         static SharedPtr<File> standard_error();
 
+        /**
+         * @brief Make this File object automatically close on the next call to execve(3).
+         */
         void set_close_on_exec();
 
+        /**
+         * @brief Write a string to this File.
+         *
+         * @param str The string to write (can be not null-terminated).
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> write(StringView str);
+
+        /**
+         * @brief Write a memory buffer to this File.
+         *
+         * @param buf The buffer to write.
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> write(const Buffer& buf);
 
+        /**
+         * @brief Read a line from this File.
+         *
+         * @return Result<String> The line as an owned String object, or an empty string if there is no more
+         * data to read.
+         */
         Result<String> read_line();
+
+        /**
+         * @brief Read the entire File's contents as a string.
+         *
+         * @return Result<String> The file's contents as an owned String object.
+         */
         Result<String> read_all_as_string();
 
+        /**
+         * @brief Read data from this File.
+         *
+         * @param buf The output buffer to store the data in. Will be resized to fit the data.
+         * @param size The maximum number of bytes to read.
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> read(Buffer& buf, usize size);
+
+        /**
+         * @brief Read the entire File's contents.
+         *
+         * @return Result<Buffer> The file's contents as an owned Buffer object.
+         */
         Result<Buffer> read_all();
 
+        /**
+         * @brief Read a single character from the File.
+         *
+         * @return Result<int> A character value above 0 (to be cast to an unsigned char), or EOF (typically -1)
+         * if there is no more data to read.
+         */
         Result<int> getchar();
 
+        /**
+         * @brief Returns the file descriptor associated with this File.
+         *
+         * @return int The file descriptor.
+         */
         int fd() const
         {
             return m_fd;
         }
 
+        /**
+         * @brief Move this File's file pointer back to the beginning.
+         */
+        void rewind();
+
         File(Badge<File>);
         ~File();
 
@@ -68,8 +185,39 @@ namespace os
         int m_fd { -1 };
     };
 
+    /**
+     * @brief Print a formatted string to standard output.
+     *
+     * @param fmt The format string (in the same format as printf(3)).
+     * @param ... The format arguments.
+     * @return Result<void> Whether the operation succeeded.
+     */
     Result<void> print(StringView fmt, ...);
+
+    /**
+     * @brief Print a newline-terminated formatted string to standard output.
+     *
+     * @param fmt The format string (in the same format as printf(3)).
+     * @param ... The format arguments.
+     * @return Result<void> Whether the operation succeeded.
+     */
     Result<void> println(StringView fmt, ...);
+
+    /**
+     * @brief Print a formatted string to standard error.
+     *
+     * @param fmt The format string (in the same format as printf(3)).
+     * @param ... The format arguments.
+     * @return Result<void> Whether the operation succeeded.
+     */
     Result<void> eprint(StringView fmt, ...);
+
+    /**
+     * @brief Print a newline-terminated formatted string to standard error.
+     *
+     * @param fmt The format string (in the same format as printf(3)).
+     * @param ... The format arguments.
+     * @return Result<void> Whether the operation succeeded.
+     */
     Result<void> eprintln(StringView fmt, ...);
 }

libos/include/os/FileSystem.h

@@ -1,31 +1,111 @@
+/**
+ * @file FileSystem.h
+ * @author apio (cloudapio.eu)
+ * @brief APIs to read and modify the general file system.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
-#include <bits/struct_stat.h>
 #include <luna/Result.h>
 #include <luna/StringView.h>
 #include <os/Path.h>
+#include <sys/stat.h>
 #include <sys/types.h>
 
 namespace os
 {
     namespace FileSystem
     {
+        /**
+         * @brief Check whether a given path exists.
+         *
+         * @param path The path to check.
+         * @param follow_symlinks If path is a symbolic link, whether to follow it (defaults to true).
+         * @return true The path exists.
+         * @return false The path does not exist, or it was a symbolic link and following it leaded to a nonexistent
+         * path.
+         */
         bool exists(const Path& path, bool follow_symlinks = true);
 
+        /**
+         * @brief Check whether a given path is a directory.
+         *
+         * @param path The path to check.
+         * @param follow_symlinks If path is a symbolic link, whether to follow it (defaults to false).
+         * @return true The path is a directory, or the path was a symbolic link and following it leaded to a directory.
+         * @return false The path does not exist, or it is not a directory.
+         */
         bool is_directory(const Path& path, bool follow_symlinks = false);
 
+        /**
+         * @brief Retrieve file status information.
+         *
+         * @param path The path to examine.
+         * @param st The buffer to store file status information in.
+         * @param follow_symlinks If path is a symbolic link, whether to follow it and retrieve its target's status, or
+         * otherwise retrieve the symbolic link's status (defaults to true).
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> stat(const Path& path, struct stat& st, bool follow_symlinks = true);
 
+        /**
+         * @brief Create a new directory in the file system.
+         *
+         * @param path The path for the new directory.
+         * @param mode The file permissions to apply to the new directory.
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> create_directory(StringView path, mode_t mode);
 
+        /**
+         * @brief Remove a file or empty directory from the file system. (The file will continue to exist if there are
+         * other hard links to it or a process still has it open.)
+         *
+         * @param path The path to remove.
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> remove(const Path& path);
 
+        /**
+         * @brief Remove a directory tree from the file system recursively, deleting subfiles and subdirectories as
+         * well.
+         *
+         * @param path The path to remove.
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> remove_tree(const Path& path);
 
+        /**
+         * @brief Read the target of a symbolic link.
+         *
+         * @param path The symbolic link's path.
+         * @return Result<String> If the path was not a symbolic link, an empty string, otherwise the symbolic link's
+         * target.
+         */
         Result<String> readlink(const Path& path);
 
+        /**
+         * @brief Read the current process's working directory.
+         *
+         * @return Result<String> The working directory as an owned String object.
+         */
         Result<String> working_directory();
+
+        /**
+         * @brief Fetch the current user' home directory.
+         *
+         * @return Result<String> The home directory as an owned String object.
+         */
         Result<String> home_directory();
 
+        /**
+         * @brief Change the current process's working directory.
+         *
+         * @param path The new working directory.
+         * @return Result<void> Whether the operation succeeded.
+         */
         Result<void> change_directory(StringView path);
     }
 }

libos/include/os/Main.h

@@ -1,4 +1,21 @@
+/**
+ * @file Main.h
+ * @author apio (cloudapio.eu)
+ * @brief Alternative C++ main function.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Result.h>
 
-Result<int> luna_main(int argc, char** argv);
+/**
+ * @brief The main() function for Luna C++ apps. This function is extern as it should be implemented by the user if they
+ * do not implement the C main() function.
+ *
+ * @param argc The argc parameter passed to the regular main() function.
+ * @param argv The argv parameter passed to the regular main() function.
+ * @return Result<int> A normal status code, or an errno code, which will be displayed along with an abnormal exit code.
+ */
+extern Result<int> luna_main(int argc, char** argv);

libos/include/os/Mode.h

@@ -1,8 +1,30 @@
+/**
+ * @file Mode.h
+ * @author apio (cloudapio.eu)
+ * @brief Visual file permissions parsing and formatting.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 
 #include <sys/types.h>
 
 namespace os
 {
+    /**
+     * @brief Create a visual representation of file permissions using the integral representation.
+     *
+     * The output is formatted in the same style as the output of "ls -l".
+     * For example:
+     * An integral mode of S_IFREG | 0644 would result in "-rw-r--r--".
+     * An integral mode of S_IFDIR | 0755 would result in "drwxr-xr-x".
+     * An integral mode of S_IFLNK | 0777 would result in "lrwxrwxrwx".
+     *
+     * @param mode The integral mode.
+     * @param out The buffer to store the formatted file permissions in, as a C-string (minimum 11 bytes, including the
+     * terminating null byte).
+     */
     void format_mode(mode_t mode, char out[11]);
 }

libos/include/os/Path.h

@@ -1,27 +1,78 @@
+/**
+ * @file Path.h
+ * @author apio (cloudapio.eu)
+ * @brief Dirfd-friendly Path class.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <fcntl.h>
 #include <luna/StringView.h>
 
 namespace os
 {
+    /**
+     * @brief A dirfd-friendly Path class.
+     */
     class Path
     {
       public:
+        /**
+         * @brief Construct a new Path object using a C-string file path.
+         *
+         * @param path The file path to use.
+         */
         Path(const char* path);
+
+        /**
+         * @brief Construct a new Path object using a StringView file path.
+         *
+         * @param path The file path to use.
+         */
         Path(StringView path);
+
+        /**
+         * @brief Construct a new Path object using a file descriptor.
+         *
+         * @param fd The file descriptor to use.
+         */
         Path(int fd);
+
+        /**
+         * @brief Construct a new Path object using a parent file descriptor and a file path.
+         *
+         * @param dirfd The parent file descriptor to use.
+         * @param name The file path to use.
+         */
         Path(int dirfd, StringView name);
 
+        /**
+         * @brief Return the file descriptor associated with this Path.
+         *
+         * @return int The file descriptor, or AT_FDCWD if this Path does not have one.
+         */
         int dirfd() const
         {
             return m_dirfd.value_or(AT_FDCWD);
         }
 
+        /**
+         * @brief Return the file path associated with this Path.
+         *
+         * @return StringView The path, or an empty StringView if this Path does not have one.
+         */
         StringView name() const
         {
             return m_name.value_or(""_sv);
         }
 
+        /**
+         * @brief Determine whether this Path consists only of a file descriptor.
+         *
+         * @return int The fstatat()-compatible flag value to use in case this Path consists only of a file descriptor.
+         */
         int is_empty_path() const
         {
             if (m_dirfd.has_value() && !m_name.has_value()) return AT_EMPTY_PATH;

libos/include/os/Process.h

@@ -1,3 +1,12 @@
+/**
+ * @file Process.h
+ * @author apio (cloudapio.eu)
+ * @brief Functions to manipulate processes.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Result.h>
 #include <luna/String.h>
@@ -5,13 +14,48 @@
 
 namespace os
 {
+    /**
+     * @brief An object representing a process.
+     */
     class Process
     {
       public:
+        /**
+         * @brief Create a new process, which is an identical copy of the current one.
+         *
+         * @return Result<pid_t> The child's process ID in the parent process, and 0 in the child process.
+         */
         static Result<pid_t> fork();
 
+        /**
+         * @brief Replace the current process's executable with another one.
+         *
+         * @param path The new executable's path.
+         * @param args The argument list to pass to the new executable.
+         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
+         * @return Result<void> Always an error, as this function does not return on success.
+         */
         static Result<void> exec(StringView path, Slice<String> args, bool search_in_path = true);
+
+        /**
+         * @brief Replace the current process's executable with another one.
+         *
+         * @param path The new executable's path.
+         * @param args The argument list to pass to the new executable.
+         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
+         * @return Result<void> Always an error, as this function does not return on success.
+         */
         static Result<void> exec(StringView path, Slice<StringView> args, bool search_in_path = true);
+
+        /**
+         * @brief Replace the current process's executable with another one.
+         *
+         * @param path The new executable's path.
+         * @param args The argument list to pass to the new executable.
+         * @param env The environment to pass to the new executable, instead of the current environment.
+         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
+         * @return Result<void> Always an error, as this function does not return on success.
+         */
         static Result<void> exec(StringView path, Slice<String> args, Slice<String> env, bool search_in_path = true);
     };
 }

libos/src/ArgumentParser.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file ArgumentParser.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Command-line argument parser.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <luna/StringBuilder.h>
 #include <os/ArgumentParser.h>
 #include <os/File.h>
@@ -75,6 +84,7 @@ namespace os
         return;
     }
 
+    // Change this every year!
     constexpr auto copyright_text = "Copyright (C) 2023, the Luna authors.";
     constexpr auto license_text = "Licensed under the BSD-2 license <https://opensource.org/license/bsd-2-clause/>";
 

libos/src/Directory.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file Directory.cpp
+ * @author apio (cloudapio.eu)
+ * @brief A C++-friendly API for directory access.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <errno.h>
 #include <fcntl.h>
 #include <luna/CString.h>

libos/src/File.cpp

@@ -1,4 +1,12 @@
-#include <fcntl.h>
+/**
+ * @file File.cpp
+ * @author apio (cloudapio.eu)
+ * @brief A C++-friendly API for file access.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <luna/StringBuilder.h>
 #include <os/File.h>
 #include <sys/syscall.h>
@@ -194,6 +202,11 @@ namespace os
         fcntl(m_fd, F_SETFD, FD_CLOEXEC);
     }
 
+    void File::rewind()
+    {
+        lseek(m_fd, 0, SEEK_SET);
+    }
+
     // FIXME: Do not allocate memory for printing.
     Result<void> print_impl(SharedPtr<File> f, StringView fmt, va_list ap)
     {

libos/src/FileSystem.cpp

@@ -1,4 +1,12 @@
-#include <bits/modes.h>
+/**
+ * @file FileSystem.cpp
+ * @author apio (cloudapio.eu)
+ * @brief APIs to read and modify the general file system.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <dirent.h>
 #include <errno.h>
 #include <fcntl.h>
@@ -33,9 +41,8 @@ namespace os::FileSystem
 
     Result<void> stat(const Path& path, struct stat& st, bool follow_symlinks)
     {
-        long rc =
+        long rc = syscall(SYS_fstatat, path.dirfd(), path.name().chars(), &st,
-            syscall(SYS_fstatat, path.dirfd(), path.name().chars(), &st,
+                          (int)(path.is_empty_path() | (follow_symlinks ? 0 : AT_SYMLINK_NOFOLLOW)));
-                    (int)((path.is_empty_path() ? AT_EMPTY_PATH : 0) | (follow_symlinks ? 0 : AT_SYMLINK_NOFOLLOW)));
 
         return Result<void>::from_syscall(rc);
     }

libos/src/Main.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file Main.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Alternative C++ main function.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <errno.h>
 #include <os/Main.h>
 #include <stdio.h>
@@ -5,6 +14,8 @@
 int g_argc;
 char** g_argv;
 
+// This function will only be linked into the final binary if the user does not already define main(), which implies
+// that they should have defined luna_main() instead. If not, good for them: linker errors!
 __attribute__((weak)) int main(int argc, char** argv)
 {
     g_argc = argc;

libos/src/Mode.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file Mode.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Visual file permissions parsing and formatting.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <os/Mode.h>
 #include <sys/stat.h>
 

libos/src/Path.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file Path.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Dirfd-friendly Path class.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <os/Path.h>
 
 namespace os

libos/src/Process.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file Process.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Functions to manipulate processes.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <errno.h>
 #include <os/Process.h>
 #include <sys/syscall.h>