doc: Add some missing doxygen comments.

diff --git a/afs.c b/afs.c
index 955b8f207d5305418674f6a0f2e30f904d110517..3f3780519ab0ddddcba6ff876ead15324b9951ec 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 e91d734fea7d70e74350cdcfdc3c4def9bce8a05..3d22e242ef94ab21b17487b345d636a01dabb3d9 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 674d1cb01e5fae9c5ae2ecb8f8ceec92fa9faa62..576bfe5bcd815ee296da0b56d49a7f3ea5d97e4e 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 9b58e22539e8277c674425f689d1f3c261c2d48a..49026db0ec91a7b4a1d3d0917723720eb8d0ba30 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 06aabe02b9934e5107ea97f1a8769af060184da7..66a17418027a5e9fa2d92bee412cf682561115b9 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 b9afc8ed637374c82918f3448695a1a2fdaa94a2..f6da52dd6cc933f66a746095389ad1510452d0e4 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 */

diff --git a/wma_common.c b/wma_common.c
index 1dde83509f2e38e8ba044fc961c381e06b74b7ca..519be89cfa2f1c3a74b7f90fea4e2045d2f6a6a7 100644 (file)
--- 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)