File-level documentation for some of src/lib.

9 files changed, 63 insertions, 0 deletions

diff --git a/src/lib/encoding/binascii.h b/src/lib/encoding/binascii.h
index 67f9eb0e87..23cbaa7070 100644
--- a/src/lib/encoding/binascii.h
+++ b/src/lib/encoding/binascii.h
@@ -4,6 +4,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file binascii.h
+ *
+ * \brief Header for binascii.c
+ **/
+
 #ifndef TOR_BINASCII_H
 #define TOR_BINASCII_H
 
diff --git a/src/lib/encoding/confline.c b/src/lib/encoding/confline.c
index 7f535b321a..3486b6a82b 100644
--- a/src/lib/encoding/confline.c
+++ b/src/lib/encoding/confline.c
@@ -4,6 +4,17 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file confline.c
+ *
+ * \brief Functions to manipulate a linked list of key-value pairs, of the
+ *   type used in Tor's configuration files.
+ *
+ * Tor uses the config_line_t type and its associated serialized format for
+ * human-readable key-value pairs in many places, including its configuration,
+ * its state files, its consensus cache, and so on.
+ **/
+
 #include "lib/encoding/confline.h"
 #include "lib/encoding/cstring.h"
 #include "lib/log/torlog.h"
diff --git a/src/lib/encoding/confline.h b/src/lib/encoding/confline.h
index f03faed5eb..41f1200947 100644
--- a/src/lib/encoding/confline.h
+++ b/src/lib/encoding/confline.h
@@ -4,6 +4,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file confline.h
+ *
+ * \brief Header for confline.c
+ **/
+
 #ifndef TOR_CONFLINE_H
 #define TOR_CONFLINE_H
 
diff --git a/src/lib/encoding/cstring.c b/src/lib/encoding/cstring.c
index 86c17f0d2c..994a52e70c 100644
--- a/src/lib/encoding/cstring.c
+++ b/src/lib/encoding/cstring.c
@@ -4,6 +4,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file cstring.c
+ *
+ * \brief Decode data that has been written as a C literal.
+ **/
+
 #include "lib/encoding/cstring.h"
 #include "lib/log/torlog.h"
 #include "lib/log/util_bug.h"
diff --git a/src/lib/encoding/cstring.h b/src/lib/encoding/cstring.h
index 3dff5e7f7f..2da109d958 100644
--- a/src/lib/encoding/cstring.h
+++ b/src/lib/encoding/cstring.h
@@ -4,6 +4,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file cstring.h
+ *
+ * \brief Header for cstring.c
+ **/
+
 #ifndef TOR_CSTRING_H
 #define TOR_CSTRING_H
 
diff --git a/src/lib/encoding/keyval.c b/src/lib/encoding/keyval.c
index cffd6f6dbc..53ee776fe7 100644
--- a/src/lib/encoding/keyval.c
+++ b/src/lib/encoding/keyval.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file keyval.c
+ *
+ * \brief Handle data encoded as a key=value pair.
+ **/
+
 #include "orconfig.h"
 #include "lib/encoding/keyval.h"
 #include "lib/log/escape.h"
diff --git a/src/lib/encoding/keyval.h b/src/lib/encoding/keyval.h
index 7458555207..8bf0797627 100644
--- a/src/lib/encoding/keyval.h
+++ b/src/lib/encoding/keyval.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file keyval.h
+ *
+ * \brief Header for keyval.c
+ **/
+
 #ifndef TOR_KEYVAL_H
 #define TOR_KEYVAL_H
 
diff --git a/src/lib/encoding/time_fmt.c b/src/lib/encoding/time_fmt.c
index ef60f17e36..ea9c8e9fd1 100644
--- a/src/lib/encoding/time_fmt.c
+++ b/src/lib/encoding/time_fmt.c
@@ -4,6 +4,16 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file time_fmt.c
+ *
+ * \brief Encode and decode time in various formats.
+ *
+ * This module is higher-level than the conversion functions in "wallclock",
+ * and handles a larger variety of types.  It converts between different time
+ * formats, and encodes and decodes them from strings.
+ **/
+
 #include "lib/encoding/time_fmt.h"
 #include "lib/log/torlog.h"
 #include "lib/log/escape.h"
diff --git a/src/lib/encoding/time_fmt.h b/src/lib/encoding/time_fmt.h
index 41508ce5e6..2892442adf 100644
--- a/src/lib/encoding/time_fmt.h
+++ b/src/lib/encoding/time_fmt.h
@@ -4,6 +4,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file time_fmt.h
+ *
+ * \brief Header for time_fmt.c
+ **/
+
 #ifndef TOR_TIME_FMT_H
 #define TOR_TIME_FMT_H