doc: Add some missing doxygen comments.
authorAndre Noll <maan@systemlinux.org>
Sat, 15 Oct 2011 19:21:07 +0000 (21:21 +0200)
committerAndre Noll <maan@systemlinux.org>
Sat, 15 Oct 2011 19:22:15 +0000 (21:22 +0200)
afs.c
aft.c
ipc.c
net.c
sched.c
vss.c
wma_common.c

diff --git a/afs.c b/afs.c
index 955b8f2..3f37805 100644 (file)
--- 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 e91d734..3d22e24 100644 (file)
--- 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 674d1cb..576bfe5 100644 (file)
--- 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 9b58e22..49026db 100644 (file)
--- 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 06aabe0..66a1741 100644 (file)
--- 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 b9afc8e..f6da52d 100644 (file)
--- 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 */
index 1dde835..519be89 100644 (file)
@@ -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)