From ebb0565e946770c5b83c4d28c1f674dffdeaf551 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Sat, 9 Feb 2008 14:05:43 +0100 Subject: [PATCH] Trivial documentation cleanups. --- close_on_fork.c | 21 ++++++++++----------- daemon.c | 46 ++++++++++++++++++++++++---------------------- exec.c | 34 ++++++++++++++++------------------ sha1.c | 2 +- signal.c | 4 ++-- 5 files changed, 53 insertions(+), 54 deletions(-) diff --git a/close_on_fork.c b/close_on_fork.c index 839802b8..4f7c2b95 100644 --- a/close_on_fork.c +++ b/close_on_fork.c @@ -1,10 +1,10 @@ /* - * Copyright (C) 2005-2006 Andre Noll + * Copyright (C) 2005-2008 Andre Noll * * Licensed under the GPL v2. For licencing details see COPYING. */ -/** \file close_on_fork.c manage a list of fds that should be closed on fork */ +/** \file close_on_fork.c Manage a list of fds that should be closed on fork. */ #include "para.h" #include "list.h" #include "string.h" @@ -13,21 +13,21 @@ static struct list_head close_on_fork_list; static int initialized; /** - * describes an element of the close-on-fork list + * Describes an element of the close-on-fork list. * * \sa list.h */ struct close_on_fork { - /** the file descriptor which should be closed after fork() */ + /** The file descriptor which should be closed after fork(). */ int fd; - /** the position in the close-on-fork list */ + /** The position in the close-on-fork list. */ struct list_head node; }; /** - * add one file descriptor to the close-on-fork list + * Add one file descriptor to the close-on-fork list. * - * \param fd the file descriptor to add + * \param fd The file descriptor to add. */ void add_close_on_fork_list(int fd) { @@ -41,11 +41,10 @@ void add_close_on_fork_list(int fd) para_list_add(&cof->node, &close_on_fork_list); } - /** - * delete one file descriptor from the close-on-fork list + * Delete one file descriptor from the close-on-fork list. * - * \param fd the file descriptor to delete + * \param fd The file descriptor to delete. * * Noop if \a fd does not belong to the close-on-fork list. */ @@ -64,7 +63,7 @@ void del_close_on_fork_list(int fd) } /** - * call close(3) for each fd in the close-on-fork list + * Call close(3) for each fd in the close-on-fork list. */ void close_listed_fds(void) { diff --git a/daemon.c b/daemon.c index 5d4cf699..a2fa1caa 100644 --- a/daemon.c +++ b/daemon.c @@ -1,10 +1,10 @@ /* - * Copyright (C) 1997-2006 Andre Noll + * Copyright (C) 1997-2008 Andre Noll * * Licensed under the GPL v2. For licencing details see COPYING. */ -/** \file daemon.c some helpers for programs that detach from the console */ +/** \file daemon.c Some helpers for programs that detach from the console. */ #include "para.h" #include "daemon.h" #include @@ -16,11 +16,11 @@ #include "string.h" /** - * do the usual stuff to become a daemon + * Do the usual stuff to become a daemon. * * Fork, become session leader, dup fd 0, 1, 2 to /dev/null. * - * \sa fork(2), setsid(2), dup(2) + * \sa fork(2), setsid(2), dup(2). */ void daemon_init(void) { @@ -48,11 +48,11 @@ void daemon_init(void) } /** - * fopen() a file in append mode + * fopen() a file in append mode. * - * \param logfile_name the name of the file to open + * \param logfile_name The name of the file to open. * - * Either calls exit() or returns a valid file handle. + * \return Either calls exit() or returns a valid file handle. */ FILE *open_log(const char *logfile_name) { @@ -70,11 +70,11 @@ FILE *open_log(const char *logfile_name) } /** - * close the log file of the daemon + * Close the log file of the daemon. * - * \param logfile the log file handle + * \param logfile The log file handle. * - * It's OK to call this with logfile == NULL + * It's OK to call this with logfile == \p NULL. */ void close_log(FILE* logfile) { @@ -85,7 +85,7 @@ void close_log(FILE* logfile) } /** - * log the startup message containing the paraslash version + * Log the startup message containing the paraslash version. */ void log_welcome(const char *whoami, int loglevel) { @@ -95,10 +95,10 @@ void log_welcome(const char *whoami, int loglevel) } /** - * give up superuser privileges + * Give up superuser privileges. * - * \param username the user to switch to - * \param groupname the group to switch to + * \param username The user to switch to. + * \param groupname The group to switch to. * * This function returns immediately if not invoked with EUID zero. Otherwise, * it tries to obtain the GID of \a groupname and the UID of \a username. On @@ -144,16 +144,18 @@ void para_drop_privileges(const char *username, const char *groupname) } /** - * set/get the server uptime + * Set/get the server uptime. * - * \param set_or_get chose one of the two modes + * \param set_or_get Chose one of the two modes. * * This should be called at startup time with \a set_or_get equal to \p * UPTIME_SET which sets the uptime to zero. Subsequent calls with \a - * set_or_get equal to \p UPTIME_GET return the number of seconds ellapsed - * since the last reset. + * set_or_get equal to \p UPTIME_GET return the uptime. + + * \return Zero if called with \a set_or_get equal to \p UPTIME_SET, the number + * of seconds ellapsed since the last reset otherwise. * - * \sa time(2), difftime(3) + * \sa time(2), difftime(3). */ time_t server_uptime(enum uptime set_or_get) { @@ -171,11 +173,11 @@ time_t server_uptime(enum uptime set_or_get) } /** - * construct string containing uptime + * Construct string containing uptime. * - * The format of the returned string is "days:hours:minutes" + * \return A dynamically allocated string of the form "days:hours:minutes". * - * \sa server_uptime + * \sa server_uptime. */ __malloc char *uptime_str(void) { diff --git a/exec.c b/exec.c index 0886a0b7..bbf1b41a 100644 --- a/exec.c +++ b/exec.c @@ -1,26 +1,26 @@ /* - * Copyright (C) 2003-2006 Andre Noll + * Copyright (C) 2003-2008 Andre Noll * * Licensed under the GPL v2. For licencing details see COPYING. */ -/** \file exec.c helper functions for spawning new processes */ +/** \file exec.c Helper functions for spawning new processes. */ #include "para.h" #include "close_on_fork.h" #include "error.h" #include "string.h" /** - * spawn a new process and redirect fd 0, 1, and 2 + * Spawn a new process and redirect fd 0, 1, and 2. * - * \param pid will hold the pid of the created process upon return - * \param file path of the executable to execute - * \param args the argument array for the command - * \param fds a pointer to a value-result array + * \param pid Will hold the pid of the created process upon return. + * \param file Path of the executable to execute. + * \param args The argument array for the command. + * \param fds a Pointer to a value-result array. * - * \return Negative on errors, positive on success. + * \return Standard. * - * \sa null(4), pipe(2), dup2(2), fork(2), exec(3) + * \sa null(4), pipe(2), dup2(2), fork(2), exec(3). */ static int para_exec(pid_t *pid, const char *file, char *const *const args, int *fds) { @@ -106,27 +106,26 @@ err_out: return ret; } - /** - * exec the given command + * Exec the given command. * - * \param pid will hold the pid of the created process upon return - * \param cmdline holds the command and its arguments, seperated by spaces - * \param fds a pointer to a value-result array + * \param pid Will hold the pid of the created process upon return. + * \param cmdline Holds the command and its arguments, seperated by spaces. + * \param fds A pointer to a value-result array. * * This function uses fork/exec to create a new process. \a fds must be a * pointer to three integers, corresponding to stdin, stdout and stderr * respectively. It specifies how to deal with fd 0, 1, 2 in the child. The * contents of \a fds are interpreted as follows: * - * - fd[i] < 0: leave fd \a i alone - * - fd[i] = 0: dup fd \a i to /dev/null + * - fd[i] < 0: leave fd \a i alone. + * - fd[i] = 0: dup fd \a i to \p /dev/null. * - fd[i] > 0: create a pipe and dup i to one end of that pipe. * Upon return, fd[i] contains the file descriptor of the pipe. * * In any case, all unneeded filedescriptors are closed. * - * \return positive on success, negative on errors + * \return Standard. */ int para_exec_cmdline_pid(pid_t *pid, const char *cmdline, int *fds) { @@ -142,4 +141,3 @@ int para_exec_cmdline_pid(pid_t *pid, const char *cmdline, int *fds) free(tmp); return ret; } - diff --git a/sha1.c b/sha1.c index 4cbbee3e..449400c1 100644 --- a/sha1.c +++ b/sha1.c @@ -8,7 +8,7 @@ * * \param data Pointer to the data to compute the hash value from. * \param len The length of \a data in bytes. - * \param sha1 Result pointer + * \param sha1 Result pointer. * * \a sha1 must point to an area at least 20 bytes large. * diff --git a/signal.c b/signal.c index 67af1655..78e788d1 100644 --- a/signal.c +++ b/signal.c @@ -1,9 +1,9 @@ /* - * Copyright (C) 2004-2006 Andre Noll + * Copyright (C) 2004-2008 Andre Noll * * Licensed under the GPL v2. For licencing details see COPYING. */ -/** \file signal.c signal handling functions */ +/** \file signal.c Signal handling functions. */ #include #include -- 2.39.2