support/doxygen: add missing doxygen tags to various functions and classes

Author: nieklinnenbank

bin/decomp/Decompress.h

@@ -57,7 +57,7 @@ class Decompress : public POSIXApplication
     /**
      * Decompress the given file
      *
-     * @param file Path to the file to decompress
+     * @param inputFilename Path to the file to decompress
      *
      * @return Result code
      */

kernel/API/PrivExec.cpp

@@ -21,7 +21,7 @@
 #include "PrivExec.h"
 
 API::Result PrivExecHandler(const PrivOperation op,
-                            const Address addr)
+                            const Address param)
 {
     DEBUG("");
 
@@ -43,7 +43,7 @@ API::Result PrivExecHandler(const PrivOperation op,
 
     case WriteConsole:
         assert(Log::instance() != ZERO);
-        (*Log::instance()) << (char *)addr;
+        (*Log::instance()) << (char *) param;
         return API::Success;
 
     case Panic:

kernel/API/PrivExec.h

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __API_PRIVEXEC_H
-#define __API_PRIVEXEC_H
+#ifndef __KERNEL_API_PRIVEXEC_H
+#define __KERNEL_API_PRIVEXEC_H
 
 /**
  * @addtogroup kernel
@@ -45,6 +45,7 @@ PrivOperation;
  * Prototype for user applications. Performs various privileged operations.
  *
  * @param op The operation to perform.
+ * @param param Optional parameter value for the given operation
  *
  * @return API::Success on success and other API::ErrorCode on failure.
  */
@@ -66,7 +67,12 @@ inline API::Result PrivExec(const PrivOperation op,
  */
 
 /**
- * Prototype for kernel handler.
+ * Prototype for kernel handler. Performs various privileged operations.
+ *
+ * @param op The operation to perform.
+ * @param param Optional parameter value for the given operation
+ *
+ * @return API::Success on success and other API::ErrorCode on failure.
  */
 extern API::Result PrivExecHandler(const PrivOperation op,
                                    const Address param);
@@ -81,4 +87,4 @@ extern API::Result PrivExecHandler(const PrivOperation op,
  * @}
  */
 
-#endif /* __API_PRIVEXEC_H */
+#endif /* __KERNEL_API_PRIVEXEC_H */

kernel/API/ProcessCtl.h

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __API_PROCESSCTL_H
-#define __API_PROCESSCTL_H
+#ifndef __KERNEL_API_PROCESSCTL_H
+#define __KERNEL_API_PROCESSCTL_H
 
 #include <FreeNOS/Process.h>
 #include <Types.h>
@@ -110,7 +110,18 @@ inline API::Result ProcessCtl(const ProcessID proc,
  */
 
 /**
- * Kernel handler prototype.
+ * Kernel handler prototype. Process management related operations.
+ *
+ * @param proc Target Process' ID.
+ * @param op The operation to perform.
+ * @param addr Input argument address, used for program entry point for Spawn,
+ *             ProcessInfo pointer for Info.
+ * @param output Output argument address (optional).
+ *
+ * @return API::Success on success and other API::ErrorCode on failure.
+ *         For WaitPID, the process exit status is stored in the upper 16-bits
+ *         of this return value on success. For Spawn, the new PID is stored in
+ *         the upper 16-bits.
  */
 extern API::Result ProcessCtlHandler(const ProcessID proc,
                                      const ProcessOperation op,
@@ -127,4 +138,4 @@ extern API::Result ProcessCtlHandler(const ProcessID proc,
  * @}
  */
 
-#endif /* __API_PROCESSCTL_H */
+#endif /* __KERNEL_API_PROCESSCTL_H */

kernel/API/ProcessID.h

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __API_PROCESSID_H
-#define __API_PROCESSID_H
+#ifndef __KERNEL_API_PROCESSID_H
+#define __KERNEL_API_PROCESSID_H
 
 /**
  * @addtogroup kernel
@@ -46,4 +46,4 @@
  * @}
  */
 
-#endif /* __API_PROCESSID_H */
+#endif /* __KERNEL_API_PROCESSID_H */

kernel/API/SystemInfo.h

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __API_SYSTEMINFO_H
-#define __API_SYSTEMINFO_H
+#ifndef __KERNEL_API_SYSTEMINFO_H
+#define __KERNEL_API_SYSTEMINFO_H
 
 #include <Types.h>
 
@@ -54,7 +54,11 @@ inline API::Result SystemInfo(SystemInformation *info)
  */
 
 /**
- * Kernel prototype.
+ * Kernel prototype. Retrieves system information.
+ *
+ * @param info Pointer to SystemInformation output buffer.
+ *
+ * @return API::Success on success and other API::ErrorCode on failure.
  */
 extern API::Result SystemInfoHandler(SystemInformation *info);
 
@@ -119,4 +123,4 @@ SystemInformation;
  * @}
  */
 
-#endif /* __API_SYSTEMINFO_H */
+#endif /* __KERNEL_API_SYSTEMINFO_H */

kernel/API/VMCopy.h

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __API_VMCOPY_H
-#define __API_VMCOPY_H
+#ifndef __KERNEL_API_VMCOPY_H
+#define __KERNEL_API_VMCOPY_H
 
 #include <Types.h>
 
@@ -60,6 +60,16 @@ inline API::Result VMCopy(const ProcessID proc,
  */
 
 /**
+ * Kernel handler prototype. Copies virtual memory between two processes.
+ *
+ * @param proc Remote process.
+ * @param how Read or Write.
+ * @param ours Virtual address of the buffer of this process.
+ * @param theirs Virtual address of the remote process' buffer.
+ * @param sz Amount of memory to copy.
+ *
+ * @return API::Success on success and any other value on error.
+ *
  * @bug VMCopyHandler assumes the theirs parameter points to memory mapped as a small page (PAGESIZE, 4KiB)
  *      When that memory is actually a large mapping (for example 1MiB on ARM), the internal pageOff variable will be zero.
  */
@@ -79,4 +89,4 @@ extern API::Result VMCopyHandler(const ProcessID proc,
  * @}
  */
 
-#endif /* __API_VMCOPY_H */
+#endif /* __KERNEL_API_VMCOPY_H */

kernel/API/VMCtl.h

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __API_VMCTL_H
-#define __API_VMCTL_H
+#ifndef __KERNEL_API_VMCTL_H
+#define __KERNEL_API_VMCTL_H
 
 #include <Types.h>
 #include <Memory.h>
@@ -76,6 +76,15 @@ inline API::Result VMCtl(const ProcessID procID,
  * @{
  */
 
+/**
+ * Kernel handler prototype. Examines and modifies virtual memory pages.
+ *
+ * @param procID Remote process.
+ * @param op Determines which operation to perform.
+ * @param range Describes the memory pages to operate on.
+ *
+ * @return API::Success on success and other API::ErrorCode on failure.
+ */
 extern API::Result VMCtlHandler(const ProcessID procID,
                                 const MemoryOperation op,
                                 Memory::Range *range);
@@ -90,4 +99,4 @@ extern API::Result VMCtlHandler(const ProcessID procID,
  * @}
  */
 
-#endif /* __API_VMCTL_H */
+#endif /* __KERNEL_API_VMCTL_H */

kernel/API/VMShare.h

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __API_VMSHARE_H
-#define __API_VMSHARE_H
+#ifndef __KERNEL_API_VMSHARE_H
+#define __KERNEL_API_VMSHARE_H
 
 #include <FreeNOS/ProcessShares.h>
 #include <Types.h>
@@ -32,10 +32,9 @@
 /**
  * Prototype for user applications. Creates and removes shared virtual memory mappings.
  *
- * @param op Determines which operation to perform.
  * @param pid Remote process.
- * @param parameter Parameter for the operation.
- * @param size Size parameter for the operation.
+ * @param op Determines which operation to perform.
+ * @param share Pointer to the MemoryShare to use in the operation
  *
  * @return API::Success on success and other API::ErrorCode on failure.
  */
@@ -57,6 +56,15 @@ inline API::Result VMShare(const ProcessID pid,
  * @{
  */
 
+/**
+ * Kernel handler prototype. Creates and removes shared virtual memory mappings.
+ *
+ * @param pid Remote process.
+ * @param op Determines which operation to perform.
+ * @param share Pointer to the MemoryShare to use in the operation
+ *
+ * @return API::Success on success and other API::ErrorCode on failure.
+ */
 extern API::Result VMShareHandler(const ProcessID pid,
                                   const API::Operation op,
                                   ProcessShares::MemoryShare *share);
@@ -71,4 +79,4 @@ extern API::Result VMShareHandler(const ProcessID pid,
  * @}
  */
 
-#endif /* __API_VMSHARE_H */
+#endif /* __KERNEL_API_VMSHARE_H */

kernel/Process.h

@@ -79,6 +79,7 @@ class Process
      * @param id Process Identifier
      * @param entry Initial program counter value.
      * @param privileged If true, the process has unlimited access to hardware.
+     * @param map Memory map to use
      */
     Process(ProcessID id, Address entry, bool privileged, const MemoryMap &map);
 
@@ -142,7 +143,7 @@ class Process
     /**
      * Compare two processes.
      *
-     * @param p Process to compare with.
+     * @param proc Process to compare with.
      *
      * @return True if equal, false otherwise.
      */

kernel/arm/ARMProcess.h

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __ARM_ARMPROCESS_H
-#define __ARM_ARMPROCESS_H
+#ifndef __KERNEL_ARM_ARMPROCESS_H
+#define __KERNEL_ARM_ARMPROCESS_H
 
 #include <FreeNOS/Process.h>
 
@@ -41,6 +41,7 @@ class ARMProcess : public Process
      * @param id Process Identifier
      * @param entry Initial program counter value.
      * @param privileged If true, the process has unlimited access to hardware.
+     * @param map Memory mapping to use to create the process.
      */
     ARMProcess(ProcessID id, Address entry, bool privileged, const MemoryMap &map);
 
@@ -109,4 +110,4 @@ namespace Arch
  * @}
  */
 
-#endif /* __ARM_ARMPROCESS_H */
+#endif /* __KERNEL_ARM_ARMPROCESS_H */

lib/liballoc/Allocator.h

@@ -105,7 +105,7 @@ class Allocator
     /**
      * Set parent allocator.
      *
-     * @param p New parent allocator.
+     * @param parent New parent allocator.
      */
     void setParent(Allocator *parent);
 
@@ -147,12 +147,12 @@ class Allocator
     /**
      * Allocate memory.
      *
-     * @param args Contains the requested size and alignment on input.
-     *             On output, contains the actual allocated address.
+     * @param range Contains the requested size and alignment on input.
+     *              On output, contains the actual allocated address.
      *
      * @return Result value.
      */
-    virtual Result allocate(Range & args);
+    virtual Result allocate(Range & range);
 
     /**
      * Release memory.

lib/liballoc/BitAllocator.h

@@ -84,7 +84,7 @@ class BitAllocator : public Allocator
      * @param args Contains the requested size and alignment on input.
      *             The alignment value must be a multiple of the chunk size.
      *             On output, contains the actual allocated address.
-     * @param bit Bit position in the bitmap array to start searching at.
+     * @param startBit Bit position in the bitmap array to start searching at.
      *
      * @return Result value.
      */

lib/liballoc/BubbleAllocator.h

@@ -68,7 +68,7 @@ class BubbleAllocator : public Allocator
      *
      * Does nothing for BubbleAllocator.
      *
-     * @param address Points to memory previously returned by allocate().
+     * @param addr Points to memory previously returned by allocate().
      *
      * @see allocate
      */

lib/liballoc/SplitAllocator.h

@@ -70,8 +70,8 @@ class SplitAllocator : public Allocator
     /**
      * Allocate sparse (non-contiguous) physical memory.
      *
-     * @param args Contains the requested size on input.
-     *             The alignment and address values are unused.
+     * @param range Contains the requested size on input.
+     *              The alignment and address values are unused.
      * @param function Called for each successful allocation of a page.
      *
      * @return Result value.

lib/libapp/ArgumentParser.cpp

@@ -92,9 +92,9 @@ void ArgumentParser::setName(const char *name)
     m_name = name;
 }
 
-void ArgumentParser::setDescription(const String & description)
+void ArgumentParser::setDescription(const String & desc)
 {
-    m_description = description;
+    m_description = desc;
 }
 
 ArgumentParser::Result ArgumentParser::registerFlag(char id,

lib/libapp/ArgumentParser.h

@@ -90,7 +90,7 @@ class ArgumentParser
      *
      * @param desc Program description string.
      */
-    void setDescription(const String & desciption);
+    void setDescription(const String & desc);
 
     /**
      * Register a flag Argument