Tidied up some of the comments and formatting

Doxyfile

@@ -983,7 +983,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = 
+USE_MDFILE_AS_MAINPAGE = README.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

README.md

@@ -1,4 +1,4 @@
-# HTTPDirFS - now with a permanent cache
+# HTTPDirFS - HTTP Directory Filesystem, with a permanent cache
 Have you ever wanted to mount those HTTP directory listings as if it was a
 partition? Look no further, this is your solution.  HTTPDirFS stands for Hyper
 Text Transfer Protocol Directory Filesystem.

src/cache.c

@@ -937,22 +937,22 @@ long Cache_read(Cache *cf, char *output_buf, off_t len, off_t offset)
     } else {
 
 #ifdef CACHE_LOCK_DEBUG
-        /* Wait for the background download thread to finish */
         fprintf(stderr,
                 "Cache_read(): thread %lu: locking and unlocking bgt_lock;\n",
                 pthread_self());
 #endif
+        /* Wait for the background download thread to finish */
         PTHREAD_MUTEX_LOCK(&cf->bgt_lock);
         PTHREAD_MUTEX_UNLOCK(&cf->bgt_lock);
 
 #ifdef CACHE_LOCK_DEBUG
-        /* Wait for any other download thread to finish*/
         fprintf(stderr, "Cache_read(): thread %lu: locking rw_lock;\n",
                 pthread_self());
 #endif
+        /* Wait for any other download thread to finish*/
         PTHREAD_MUTEX_LOCK(&cf->rw_lock);
         if (Seg_exist(cf, offset)) {
-            /* The segment already exists - it was downloaded by other
+            /* The segment now exists - it was downloaded by another
              * download thread. Send it off and unlock the I/O */
             send = Data_read(cf, (uint8_t *) output_buf, len, offset);
 #ifdef CACHE_LOCK_DEBUG

src/cache.h

@@ -1,6 +1,14 @@
 #ifndef CACHE_H
 #define CACHE_H
 
+/**
+ * \file cache.h
+ * \brief cache related structures and functions
+ * \details
+ *   - We store the metadata and the actual data separately in two
+ * separate folders.
+ */
+
 #include <pthread.h>
 
 /**
@@ -10,14 +18,6 @@ typedef struct Cache Cache;
 
 #include "link.h"
 
-/**
- * \file cache.h
- * \brief cache related structures and functions
- * \details
- *   - We store the metadata and the actual data separately in two
- * separate folders.
- */
-
 /**
  * \brief Type definition for a cache segment
  */
@@ -100,7 +100,7 @@ void Cache_close(Cache *cf);
 /**
  * \brief create a cache file set if it doesn't exist already
  * \return
- *  -   0, if the cache file already exists, or was created succesfully.
+ *  -   0, if the cache file already exists, or was created successfully.
  *  -   -1, otherwise
  * \note Called by fs_open()
  */

src/fuse_local.h

@@ -1,6 +1,11 @@
 #ifndef FUSE_LOCAL_H
 #define FUSE_LOCAL_H
 
+/**
+ * \file fuse_local.h
+ * \brief FUSE related functions
+ */
+
 /* Initialise fuse */
 int fuse_local_init(int argc, char **argv);
 

src/link.h

@@ -1,6 +1,11 @@
 #ifndef LINK_H
 #define LINK_H
 
+/**
+ * \file link.h
+ * \brief link related structures and functions
+ */
+
 #include "util.h"
 
 #include <curl/curl.h>
@@ -60,12 +65,12 @@ extern int ROOT_LINK_OFFSET;
 void link_system_init();
 
 /**
- * \brief
+ * \brief Add a link to the curl multi bundle for querying stats
  */
 void Link_get_stat(Link *this_link);
 
 /**
- * \brief set the stats for a file
+ * \brief Set the stats of a link, after curl multi handle finished querying
  */
 void Link_set_stat(Link* this_link, CURL *curl);
 

src/network.c

@@ -33,8 +33,8 @@ static pthread_mutex_t curl_lock;
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wunused-function"
 /**
- * \note
+ * \brief OpenSSL 1.02 cryptography callback function
- * Required for OpenSSL 1.02, but not OpenSSL 1.1
+ * \details Required for OpenSSL 1.02, but not OpenSSL 1.1
  */
 static void crypto_lock_callback(int mode, int type, char *file, int line)
 {
@@ -48,8 +48,8 @@ static void crypto_lock_callback(int mode, int type, char *file, int line)
 }
 
 /**
- * \note
+ * \brief OpenSSL 1.02 thread ID function
- * Required for OpenSSL 1.02, but not OpenSSL 1.1
+ * \details Required for OpenSSL 1.02, but not OpenSSL 1.1
  */
 static unsigned long thread_id(void)
 {
@@ -75,7 +75,8 @@ static void crypto_lock_init(void)
 }
 
 /**
- * \note Adapted from:
+ * \brief Curl share handle callback function
+ * \details Adapted from:
  * https://curl.haxx.se/libcurl/c/threaded-shared-conn.html
  */
 static void curl_callback_lock(CURL *handle, curl_lock_data data,
@@ -98,7 +99,8 @@ static void curl_callback_unlock(CURL *handle, curl_lock_data data,
 }
 
 /**
- * \note Adapted from:
+ * \brief Process a curl message
+ * \details Adapted from:
  * https://curl.haxx.se/libcurl/c/10-at-a-time.html
  */
 static void curl_process_msgs(CURLMsg *curl_msg, int n_running_curl,
@@ -155,7 +157,7 @@ static void curl_process_msgs(CURLMsg *curl_msg, int n_running_curl,
 }
 
 /**
- * \note  effectively based on
+ * \details  effectively based on
  * https://curl.haxx.se/libcurl/c/multi-double.html
  */
 int curl_multi_perform_once()

src/network.h

@@ -1,6 +1,11 @@
 #ifndef NETWORK_H
 #define NETWORK_H
 
+/**
+ * \file network.h
+ * \brief network related functions
+ */
+
 #include "link.h"
 
 typedef enum {
@@ -8,7 +13,7 @@ typedef enum {
     HTTP_PARTIAL_CONTENT        = 206,
     HTTP_RANGE_NOT_SATISFIABLE  = 416,
     HTTP_TOO_MANY_REQUESTS      = 429
-}HTTPResponseCode;
+} HTTPResponseCode;
 
 typedef enum {
     FILESTAT = 's',

src/util.h

@@ -8,17 +8,18 @@
 #include <stdint.h>
 #include <stdlib.h>
 
-#define PTHREAD_MUTEX_UNLOCK(x)\
+/**
-({\
+ * \brief the maximum length of a path and a URL.
-    int i;\
+ * \details This corresponds the maximum path length under Ext4.
-    i = pthread_mutex_unlock(x);\
+ */
-    if (i) { \
+#define MAX_PATH_LEN        4096
-        fprintf(stderr, "pthread_mutex_unlock failed, %d, %s\n", i, \
-        strerror(i));\
-        exit(EXIT_FAILURE);\
-    }\
-})
 
+/** \brief the maximum length of a filename. */
+#define MAX_FILENAME_LEN    255
+
+/**
+ * \brief wrapper for pthread_mutex_lock()
+ */
 #define PTHREAD_MUTEX_LOCK(x)\
 ({\
     int i;\
@@ -31,13 +32,18 @@
 })
 
 /**
- * \brief the maximum length of a path and a URL.
+ * \brief wrapper for pthread_mutex_unlock()
- * \details This corresponds the maximum path length under Ext4.
  */
-#define MAX_PATH_LEN        4096
+#define PTHREAD_MUTEX_UNLOCK(x)\
-
+({\
-/** \brief the maximum length of a filename. */
+    int i;\
-#define MAX_FILENAME_LEN    255
+    i = pthread_mutex_unlock(x);\
+    if (i) { \
+        fprintf(stderr, "pthread_mutex_unlock failed, %d, %s\n", i, \
+        strerror(i));\
+        exit(EXIT_FAILURE);\
+    }\
+})
 
 /**
  * \brief append a path