24 files changed, 64 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
diff --git a/public-inbox-init b/public-inbox-init
index d6a63822..d66361df 100755
--- a/public-inbox-init
+++ b/public-inbox-init
@@ -1,6 +1,8 @@
  #!/usr/bin/perl -w
  # Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
  # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Initializes a public-inbox, basically a wrapper for git-init(1)
  use strict;
  use warnings;
  my $usage = "public-inbox-init NAME GIT_DIR HTTP_URL ADDRESS [ADDRESS..]";
diff --git a/public-inbox-learn b/public-inbox-learn
index 3b0dae8e..0c7b4199 100755
--- a/public-inbox-learn
+++ b/public-inbox-learn
@@ -1,6 +1,9 @@
  #!/usr/bin/perl -w
  # 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 training spam (via SpamAssassin) and removing messages from a
+# public-inbox
  my $usage = "$0 (spam|ham) < /path/to/message";
  use strict;
  use warnings;
diff --git a/public-inbox-mda b/public-inbox-mda
index df8ca38c..73c4ae1c 100755
--- a/public-inbox-mda
+++ b/public-inbox-mda
@@ -1,6 +1,8 @@
  #!/usr/bin/perl -w
  # Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
  # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Mail delivery agent for public-inbox, run from your MTA upon mail delivery
  use strict;
  use warnings;
  my $usage = 'public-inbox-mda < rfc2822_message';
diff --git a/public-inbox-nntpd b/public-inbox-nntpd
index 0035637d..1f0cd377 100755
--- a/public-inbox-nntpd
+++ b/public-inbox-nntpd
@@ -1,6 +1,8 @@
  #!/usr/bin/perl -w
  # Copyright (C) 2015 all contributors <meta@public-inbox.org>
  # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Standalone NNTP server for public-inbox.
  use strict;
  use warnings;
  require PublicInbox::Daemon;
diff --git a/public-inbox.cgi b/public-inbox.cgi
index 157cf6a2..4b74a62a 100755
--- a/public-inbox.cgi
+++ b/public-inbox.cgi
@@ -1,6 +1,8 @@
  #!/usr/bin/perl -w
  # Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
  # License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Enables using PublicInbox::WWW as a CGI script
  use strict;
  use warnings;
  use IO::Handle;