From 89f2de1016601e523fd456e0e2fa650fa695ecaa Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sat, 15 Oct 2011 21:21:07 +0200
Subject: [PATCH] doc: Add some missing doxygen comments.

---
 afs.c        | 9 +++++++--
 aft.c        | 2 ++
 ipc.c        | 9 +++++++++
 net.c        | 8 +++++---
 sched.c      | 4 ++--
 vss.c        | 1 +
 wma_common.c | 2 ++
 7 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/afs.c b/afs.c
index 955b8f20..3f378051 100644
--- a/afs.c
+++ b/afs.c
@@ -286,6 +286,9 @@ out:
  * command. This function allows to pass such a structure together with a list
  * of further arguments (often a list of audio files) to the parent process.
  *
+ * \return The return value of the underlying call to \ref
+ * send_callback_request().
+ *
  * \sa send_standard_callback_request(), send_callback_request().
  */
 int send_option_arg_callback_request(struct osl_object *options,
@@ -1146,7 +1149,8 @@ void afs_event(enum afs_events event, struct para_buffer *pb,
  * \param pb Unused.
  * \param data Unused.
  *
- * This table does not honor events.
+ * \return The images table does not honor events, so this handler always
+ * returns success.
  */
 __a_const int images_event_handler(__a_unused enum afs_events event,
 	__a_unused  struct para_buffer *pb, __a_unused void *data)
@@ -1161,7 +1165,8 @@ __a_const int images_event_handler(__a_unused enum afs_events event,
  * \param pb Unused.
  * \param data Unused.
  *
- * This table does not honor events.
+ * \return The lyrics table does not honor events, so this handler always
+ * returns success.
  */
 __a_const int lyrics_event_handler(__a_unused enum afs_events event,
 	__a_unused struct para_buffer *pb, __a_unused void *data)
diff --git a/aft.c b/aft.c
index e91d734f..3d22e242 100644
--- a/aft.c
+++ b/aft.c
@@ -2481,6 +2481,8 @@ static void afs_stat_callback(int fd, const struct osl_object *query)
  * up-to-date afs status items directly. Therefore the usual callback mechanism
  * is used to pass the status items from the afs process to the command handler
  * via a shared memory area and a pipe.
+ *
+ * \return The return value of the underyling call to \ref send_callback_request().
  */
 int send_afs_status(struct stream_cipher_context *scc, int parser_friendly)
 {
diff --git a/ipc.c b/ipc.c
index 674d1cb0..576bfe5b 100644
--- a/ipc.c
+++ b/ipc.c
@@ -184,6 +184,15 @@ int shm_detach(void *addr)
 #	undef SYSCTL_SHMMAX_VARIABLE
 # endif
 
+/**
+ * Get the maximal size of a shared memory area.
+ *
+ * The value is only computed once when the function is called for the first
+ * time.  Subsequent calls return the number which was computed during the
+ * first call.
+ *
+ * \return A number suitable as an argument to \ref shm_new().
+ */
 size_t shm_get_shmmax(void)
 {
 	static size_t shmmax;
diff --git a/net.c b/net.c
index 9b58e225..49026db0 100644
--- a/net.c
+++ b/net.c
@@ -578,10 +578,12 @@ static inline int estimated_header_overhead(const int af_type)
 /**
  * Get the maximum transport-layer message size (MMS_S).
  *
- * The socket must be connected. See RFC 1122, 3.3.3.
+ * \param sockfd The socket file descriptor.
  *
- * \return If the protocol familiy could not be determined, \p AF_INET is
- * assumed.
+ * The socket must be connected. See RFC 1122, 3.3.3. If the protocol familiy
+ * could not be determined, \p AF_INET is assumed.
+ *
+ * \return The maximum message size of the address family type.
  */
 int generic_max_transport_msg_size(int sockfd)
 {
diff --git a/sched.c b/sched.c
index 06aabe02..66a17418 100644
--- a/sched.c
+++ b/sched.c
@@ -335,8 +335,8 @@ int sched_request_barrier(struct timeval *barrier, struct sched *s)
  * \param barrier Absolute time before select() should return.
  * \param s Pointer to the scheduler struct.
  *
- * If \a barrier is in the past, this function requests a minimal timeout and
- * returns zero. Otherwise it returns one.
+ * \return If \a barrier is in the past, this function requests a minimal
+ * timeout and returns zero. Otherwise it returns one.
  *
  * \sa sched_min_delay(), sched_request_barrier().
  */
diff --git a/vss.c b/vss.c
index b9afc8ed..f6da52dd 100644
--- a/vss.c
+++ b/vss.c
@@ -132,6 +132,7 @@ struct fec_group {
 	uint16_t slice_bytes;
 };
 
+/** A FEC client is always in one of these states. */
 enum fec_client_state {
 	FEC_STATE_NONE = 0,	/**< not initialized and not enabled */
 	FEC_STATE_DISABLED,	/**< temporarily disabled */
diff --git a/wma_common.c b/wma_common.c
index 1dde8350..519be89c 100644
--- a/wma_common.c
+++ b/wma_common.c
@@ -28,6 +28,8 @@
  * \param pattern_len The length of the pattern in bytes.
  * \param buf The buffer to search for the pattern.
  * \param buf_size The number of bytes in \a buf.
+ *
+ * \return A pointer into \a buf or \p NULL if the pattern was not found.
  */
 const char *search_pattern(const char *pattern, int pattern_len,
 		const char *buf, int buf_size)
-- 
2.39.2