various internal documentation updates

Hopefully this gives new hackers a better overview of
how the components relate to each other.

19 files changed, 53 insertions, 4 deletions

diff --git a/lib/PublicInbox/Config.pm b/lib/PublicInbox/Config.pm
index 0d73a867..8da00b0a 100644
--- a/lib/PublicInbox/Config.pm
+++ b/lib/PublicInbox/Config.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used throughout the project for reading configuration
 package PublicInbox::Config;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/ExtMsg.pm b/lib/PublicInbox/ExtMsg.pm
index 0cba49dd..50680471 100644
--- a/lib/PublicInbox/ExtMsg.pm
+++ b/lib/PublicInbox/ExtMsg.pm
@@ -1,5 +1,10 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used by the web interface to link to messages outside of the our
+# public-inboxes.  Mail threads may cross projects/threads; so
+# we should ensure users can find more easily find them on other
+# sites.
 package PublicInbox::ExtMsg;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Feed.pm b/lib/PublicInbox/Feed.pm
index e66b678b..1201dd11 100644
--- a/lib/PublicInbox/Feed.pm
+++ b/lib/PublicInbox/Feed.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used for generating Atom feeds for web-accessible mailing list archives.
 package PublicInbox::Feed;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Filter.pm b/lib/PublicInbox/Filter.pm
index 82baa9b9..ea6fd33f 100644
--- a/lib/PublicInbox/Filter.pm
+++ b/lib/PublicInbox/Filter.pm
@@ -1,6 +1,7 @@
 # Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
 #
+# Used to filter incoming mail for -mda and importers
 # This only exposes one function: run
 # Note: the settings here are highly opinionated.  Obviously, this is
 # Free Software (AGPLv3), so you may change it if you host yourself.
diff --git a/lib/PublicInbox/GitCatFile.pm b/lib/PublicInbox/GitCatFile.pm
index 629d23ed..dd95d5f3 100644
--- a/lib/PublicInbox/GitCatFile.pm
+++ b/lib/PublicInbox/GitCatFile.pm
@@ -1,5 +1,8 @@
 # Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
 # License: GPLv2 or later (https://www.gnu.org/licenses/gpl-2.0.txt)
+#
+# Used to read files from a git repository without excessive forking.
+# Used in our web interfaces as well as our -nntpd server.
 # This is based on code in Git.pm which is GPLv2, but modified to avoid
 # dependence on environment variables for compatibility with mod_perl.
 # There are also API changes to simplify our usage and data set.
diff --git a/lib/PublicInbox/Hval.pm b/lib/PublicInbox/Hval.pm
index 9fbe616f..ab6e044b 100644
--- a/lib/PublicInbox/Hval.pm
+++ b/lib/PublicInbox/Hval.pm
@@ -1,7 +1,8 @@
 # Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
 #
-# represents a header value in various forms
+# represents a header value in various forms.  Used for HTML generation
+# in our web interface(s)
 package PublicInbox::Hval;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Listener.pm b/lib/PublicInbox/Listener.pm
index 7f9658b8..67817d9f 100644
--- a/lib/PublicInbox/Listener.pm
+++ b/lib/PublicInbox/Listener.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used by -nntpd for listen sockets
 package PublicInbox::Listener;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/MDA.pm b/lib/PublicInbox/MDA.pm
index 7025fb3c..ba5f36b0 100644
--- a/lib/PublicInbox/MDA.pm
+++ b/lib/PublicInbox/MDA.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# For the -mda script (mail delivery agent)
 package PublicInbox::MDA;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/MID.pm b/lib/PublicInbox/MID.pm
index 3d404ef8..169ffa76 100644
--- a/lib/PublicInbox/MID.pm
+++ b/lib/PublicInbox/MID.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Various Message-ID-related functions.
 package PublicInbox::MID;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Mbox.pm b/lib/PublicInbox/Mbox.pm
index 80e8efc9..c180a0dc 100644
--- a/lib/PublicInbox/Mbox.pm
+++ b/lib/PublicInbox/Mbox.pm
@@ -1,6 +1,8 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
-# Streaming interface for formatting messages as an mboxrd
+
+# Streaming interface for formatting messages as an mboxrd.
+# Used by the web interface
 package PublicInbox::Mbox;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Msgmap.pm b/lib/PublicInbox/Msgmap.pm
index 6e9f2743..8fe17a95 100644
--- a/lib/PublicInbox/Msgmap.pm
+++ b/lib/PublicInbox/Msgmap.pm
@@ -1,6 +1,12 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
-# bidirectional Message-ID <-> Article Number mapping
+
+# bidirectional Message-ID <-> Article Number mapping for the NNTP
+# and web interfaces.  This is required for implementing stable article
+# numbers for NNTP and allows prefix lookups for partial Message-IDs
+# in case URLs get truncated from copy-n-paste errors by users.
+#
+# This is maintained by ::SearchIdx
 package PublicInbox::Msgmap;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/NNTP.pm b/lib/PublicInbox/NNTP.pm
index 0bfafa88..295aee0e 100644
--- a/lib/PublicInbox/NNTP.pm
+++ b/lib/PublicInbox/NNTP.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Each instance of this represents a NNTP client socket
 package PublicInbox::NNTP;
 use strict;
 use warnings;
@@ -897,7 +899,7 @@ sub do_more ($$) {
         $self->do_write($data);
 }
 
-# callbacks for by Danga::Socket
+# callbacks for Danga::Socket
 
 sub event_hup { $_[0]->close }
 sub event_err { $_[0]->close }
diff --git a/lib/PublicInbox/NewsGroup.pm b/lib/PublicInbox/NewsGroup.pm
index 02e90111..3a318958 100644
--- a/lib/PublicInbox/NewsGroup.pm
+++ b/lib/PublicInbox/NewsGroup.pm
@@ -1,5 +1,8 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used only by the NNTP server to represent a public-inbox git repository
+# as a newsgroup
 package PublicInbox::NewsGroup;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Search.pm b/lib/PublicInbox/Search.pm
index fbc6882c..0f7815fb 100644
--- a/lib/PublicInbox/Search.pm
+++ b/lib/PublicInbox/Search.pm
@@ -1,6 +1,8 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
 # based on notmuch, but with no concept of folders, files or flags
+#
+# Read-only search interface for use by the web and NNTP interfaces
 package PublicInbox::Search;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/SearchIdx.pm b/lib/PublicInbox/SearchIdx.pm
index 0646cfb3..e9af547f 100644
--- a/lib/PublicInbox/SearchIdx.pm
+++ b/lib/PublicInbox/SearchIdx.pm
@@ -1,6 +1,11 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
 # based on notmuch, but with no concept of folders, files or flags
+#
+# Indexes mail with Xapian and our (SQLite-based) ::Msgmap for use
+# with the web and NNTP interfaces.  This index maintains thread
+# relationships for use by Mail::Thread.  This writes to the search
+# index.
 package PublicInbox::SearchIdx;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/SearchMsg.pm b/lib/PublicInbox/SearchMsg.pm
index 8d49ee20..93be7475 100644
--- a/lib/PublicInbox/SearchMsg.pm
+++ b/lib/PublicInbox/SearchMsg.pm
@@ -1,6 +1,8 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: GPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
 # based on notmuch, but with no concept of folders, files or flags
+#
+# Wraps a document inside our Xapian search index.
 package PublicInbox::SearchMsg;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/SearchView.pm b/lib/PublicInbox/SearchView.pm
index a51acbb4..a15af55e 100644
--- a/lib/PublicInbox/SearchView.pm
+++ b/lib/PublicInbox/SearchView.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Displays search results for the web interface
 package PublicInbox::SearchView;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/View.pm b/lib/PublicInbox/View.pm
index 92fedd19..15d846a6 100644
--- a/lib/PublicInbox/View.pm
+++ b/lib/PublicInbox/View.pm
@@ -1,5 +1,8 @@
 # Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Used for displaying the HTML web interface.
+# See Documentation/design_www.txt for this.
 package PublicInbox::View;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/WWW.pm b/lib/PublicInbox/WWW.pm
index fb57163e..d00dfe7c 100644
--- a/lib/PublicInbox/WWW.pm
+++ b/lib/PublicInbox/WWW.pm
@@ -1,6 +1,8 @@
 # Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
 # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
 #
+# Main web interface for mailing list archives
+#
 # We focus on the lowest common denominators here:
 # - targeted at text-only console browsers (w3m, links, etc..)
 # - Only basic HTML, CSS only for line-wrapping <pre> text content for GUIs