File-level documentation for some of src/lib.

19 files changed, 124 insertions, 0 deletions

diff --git a/src/lib/fs/conffile.c b/src/lib/fs/conffile.c
index 37bd9f0368..600c7f6b70 100644
--- a/src/lib/fs/conffile.c
+++ b/src/lib/fs/conffile.c
@@ -4,6 +4,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file conffile.h
+ *
+ * \brief Read configuration files from disk, with full `%include` support.
+ **/
+
 #include "lib/fs/conffile.h"
 
 #include "lib/container/smartlist.h"
diff --git a/src/lib/fs/conffile.h b/src/lib/fs/conffile.h
index bd8250b002..a926f4ac05 100644
--- a/src/lib/fs/conffile.h
+++ b/src/lib/fs/conffile.h
@@ -7,6 +7,12 @@
 #ifndef TOR_CONFFILE_H
 #define TOR_CONFFILE_H
 
+/**
+ * \file conffile.h
+ *
+ * \brief Header for conffile.c
+ **/
+
 struct smartlist_t;
 struct config_line_t;
 
diff --git a/src/lib/fs/dir.c b/src/lib/fs/dir.c
index 9f09327d84..cc339f747e 100644
--- a/src/lib/fs/dir.c
+++ b/src/lib/fs/dir.c
@@ -3,6 +3,13 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file dir.c
+ *
+ * \brief Read directories, and create directories with restrictive
+ * permissions.
+ **/
+
 #include "lib/fs/dir.h"
 #include "lib/fs/path.h"
 #include "lib/fs/userdb.h"
diff --git a/src/lib/fs/dir.h b/src/lib/fs/dir.h
index 925211fbd6..61a04e6d58 100644
--- a/src/lib/fs/dir.h
+++ b/src/lib/fs/dir.h
@@ -6,6 +6,12 @@
 #ifndef TOR_DIR_H
 #define TOR_DIR_H
 
+/**
+ * \file dir.h
+ *
+ * \brief Header for dir.c
+ **/
+
 #include "lib/cc/compat_compiler.h"
 #include "lib/testsupport/testsupport.h"
 
diff --git a/src/lib/fs/files.c b/src/lib/fs/files.c
index 0335f6dc59..4e0a398baa 100644
--- a/src/lib/fs/files.c
+++ b/src/lib/fs/files.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file files.h
+ *
+ * \brief Wrappers for reading and writing data to files on disk.
+ **/
+
 #ifdef _WIN32
 #include <windows.h>
 #endif
diff --git a/src/lib/fs/files.h b/src/lib/fs/files.h
index be4ec485f1..5a12eb8215 100644
--- a/src/lib/fs/files.h
+++ b/src/lib/fs/files.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file files.h
+ *
+ * \brief Header for files.c
+ **/
+
 #ifndef TOR_FS_H
 #define TOR_FS_H
 
diff --git a/src/lib/fs/freespace.c b/src/lib/fs/freespace.c
index 926b17dbde..2dbba3c5f8 100644
--- a/src/lib/fs/freespace.c
+++ b/src/lib/fs/freespace.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file freespace.c
+ *
+ * \brief Find the available disk space on the current volume.
+ **/
+
 #include "lib/fs/files.h"
 #include "lib/cc/torint.h"
 
diff --git a/src/lib/fs/lockfile.c b/src/lib/fs/lockfile.c
index 3fc9cd4264..972fd5658d 100644
--- a/src/lib/fs/lockfile.c
+++ b/src/lib/fs/lockfile.c
@@ -3,6 +3,13 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file lockfile.c
+ *
+ * \brief Implements lock files to prevent two Tor processes from using the
+ * same data directory at the same time.
+ **/
+
 #include "orconfig.h"
 #include "lib/fs/files.h"
 #include "lib/fs/lockfile.h"
diff --git a/src/lib/fs/lockfile.h b/src/lib/fs/lockfile.h
index 1c5bb023b5..e26349811c 100644
--- a/src/lib/fs/lockfile.h
+++ b/src/lib/fs/lockfile.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file lockfile.h
+ *
+ * \brief Header for lockfile.c
+ **/
+
 #ifndef TOR_LOCKFILE_H
 #define TOR_LOCKFILE_H
 
diff --git a/src/lib/fs/mmap.c b/src/lib/fs/mmap.c
index 6d69fd5e78..2d758c1b5f 100644
--- a/src/lib/fs/mmap.c
+++ b/src/lib/fs/mmap.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file mmap.c
+ *
+ * \brief Cross-platform support for mapping files into our address space.
+ **/
+
 #include "lib/fs/mmap.h"
 #include "lib/fs/files.h"
 #include "lib/log/torlog.h"
diff --git a/src/lib/fs/mmap.h b/src/lib/fs/mmap.h
index b0585775f5..125f368802 100644
--- a/src/lib/fs/mmap.h
+++ b/src/lib/fs/mmap.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file mmap.h
+ *
+ * \brief Header for mmap.c
+ **/
+
 #ifndef TOR_MMAP_H
 #define TOR_MMAP_H
 
diff --git a/src/lib/fs/path.c b/src/lib/fs/path.c
index 68cda67765..708ff0505a 100644
--- a/src/lib/fs/path.c
+++ b/src/lib/fs/path.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file path.c
+ *
+ * \brief Manipulate strings that contain filesystem paths.
+ **/
+
 #include "lib/fs/path.h"
 #include "lib/malloc/util_malloc.h"
 #include "lib/log/torlog.h"
diff --git a/src/lib/fs/path.h b/src/lib/fs/path.h
index a3073a99ec..384d1f514f 100644
--- a/src/lib/fs/path.h
+++ b/src/lib/fs/path.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file path.h
+ *
+ * \brief Header for path.c
+ **/
+
 #ifndef TOR_PATH_H
 #define TOR_PATH_H
 
diff --git a/src/lib/fs/storagedir.c b/src/lib/fs/storagedir.c
index d013e4550d..1cda2374d8 100644
--- a/src/lib/fs/storagedir.c
+++ b/src/lib/fs/storagedir.c
@@ -1,6 +1,17 @@
 /* Copyright (c) 2017-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file storagedir.c
+ *
+ * \brief An abstraction for a directory full of similar files.
+ *
+ * Storagedirs are used by our consensus cache code, and may someday also get
+ * used for unparseable objects. A large part of the need for this type is to
+ * work around the limitations in our sandbox code, where all filenames need
+ * to be registered in advance.
+ **/
+
 #include "lib/fs/storagedir.h"
 
 #include "lib/container/smartlist.h"
diff --git a/src/lib/fs/storagedir.h b/src/lib/fs/storagedir.h
index 1ecb1c0a11..58594b4634 100644
--- a/src/lib/fs/storagedir.h
+++ b/src/lib/fs/storagedir.h
@@ -1,6 +1,12 @@
 /* Copyright (c) 2017-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file storagedir.h
+ *
+ * \brief Header for storagedir.c
+ **/
+
 #ifndef TOR_STORAGEDIR_H
 #define TOR_STORAGEDIR_H
 
diff --git a/src/lib/fs/userdb.c b/src/lib/fs/userdb.c
index b7abbc7813..3d7a9da59d 100644
--- a/src/lib/fs/userdb.c
+++ b/src/lib/fs/userdb.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file userdb.c
+ *
+ * \brief Access the POSIX user database.
+ **/
+
 #include "lib/fs/userdb.h"
 
 #ifndef _WIN32
diff --git a/src/lib/fs/userdb.h b/src/lib/fs/userdb.h
index 31c891ede8..3b3ab6ed2b 100644
--- a/src/lib/fs/userdb.h
+++ b/src/lib/fs/userdb.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file userdb.h
+ *
+ * \brief Header for userdb.c
+ **/
+
 #ifndef TOR_USERDB_H
 #define TOR_USERDB_H
 
diff --git a/src/lib/fs/winlib.c b/src/lib/fs/winlib.c
index 7a88a841a6..532807c03f 100644
--- a/src/lib/fs/winlib.c
+++ b/src/lib/fs/winlib.c
@@ -3,6 +3,15 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file winlib.c
+ *
+ * \brief Find and load windows system libraries.
+ *
+ * We use this function to dynamically load code at runtime that might not be
+ * available on all versions of Windows that we support.
+ **/
+
 #ifdef _WIN32
 #include "lib/fs/winlib.h"
 
diff --git a/src/lib/fs/winlib.h b/src/lib/fs/winlib.h
index f53f046451..5b10b9b78d 100644
--- a/src/lib/fs/winlib.h
+++ b/src/lib/fs/winlib.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file winlib.h
+ *
+ * \brief Header for winlib.c
+ **/
+
 #ifndef TOR_WINLIB_H
 #define TOR_WINLIB_H