Merge branch 'refs/heads/t/doxygen'

[paraslash.git] / aft.c

diff --git a/aft.c b/aft.c
index 99d53393c750f3041588ca2d45a5d029e02ebd60..c2642ed3d13ceb139335cdef0c06c6999cd2ae7b 100644 (file)
--- a/aft.c
+++ b/aft.c
@@ -365,7 +365,10 @@ static void save_afhi(struct afh_info *afhi, char *buf)
        write_u32(buf + CHUNK_TV_TV_SEC_OFFSET, afhi->chunk_tv.tv_sec);
        write_u32(buf + CHUNK_TV_TV_USEC_OFFSET, afhi->chunk_tv.tv_usec);
        p = buf + AFHI_INFO_STRING_OFFSET;
-       /* The sprintf's below are OK as our caller made sure that buf is large enough */
+       /*
+        * The below sprintf(3) calls are OK because our caller already made
+        * sure that buf is large enough.
+        */
        p += sprintf(p, "%s", afhi->techinfo) + 1;
        p += sprintf(p, "%s", afhi->tags.artist) + 1;
        p += sprintf(p, "%s", afhi->tags.title) + 1;
@@ -374,6 +377,7 @@ static void save_afhi(struct afh_info *afhi, char *buf)
        sprintf(p, "%s", afhi->tags.comment);
 }
 
+/* does not load the chunk table */
 static void load_afhi(const char *buf, struct afh_info *afhi)
 {
        afhi->seconds_total = read_u32(buf + AFHI_SECONDS_TOTAL_OFFSET);
@@ -528,7 +532,7 @@ static int get_afsi_of_path(const char *path, struct afs_info *afsi)
  * \param row Pointer to a row in the audio file table.
  * \param path Result pointer.
  *
- * The result is a pointer to mmapped data. The caller must not attempt
+ * The result is a pointer to memory-mapped data. The caller must not attempt
  * to free it.
  *
  * \return Standard.
@@ -589,6 +593,10 @@ static int get_hash_of_row(const struct osl_row *row, unsigned char **hash)
  * \param afhi Result pointer.
  *
  * \return The return value of the underlying call to osl_get_object().
+ *
+ * After the call the members of the afhi structure point to mapped memory
+ * which is owned by the osl table, Hence the caller must not attempt to free
+ * this memory by calling \ref clear_afhi().
  */
 int get_afhi_of_row(const struct osl_row *row, struct afh_info *afhi)
 {
@@ -692,7 +700,7 @@ static int get_local_time(uint64_t *seconds, char *buf, size_t size,
        /*
         * If the given time is more than six month away from the current time,
         * we print only the year. The additional space character in the format
-        * string below makes the formated date align nicely with dates that
+        * string below makes the formatted date align nicely with dates that
         * contain the time (those written by the above strftime() statement).
         */
        if (!strftime(buf, size, "%b %e  %Y", tm))