[PATCH] doc: various overview-level module comments

[PATCH] doc: various overview-level module comments

[Eric Wong]

Hopefully this helps people familiarize themselves with
the source code.
---
 lib/PublicInbox/AltId.pm               | 9 +++++++++
 lib/PublicInbox/ContentId.pm           | 5 +++++
 lib/PublicInbox/GetlineBody.pm         | 4 ++++
 lib/PublicInbox/GitHTTPBackend.pm      | 2 +-
 lib/PublicInbox/HTTPD.pm               | 2 ++
 lib/PublicInbox/Import.pm              | 5 +++--
 lib/PublicInbox/Mbox.pm                | 8 ++++++--
 lib/PublicInbox/MsgIter.pm             | 3 ++-
 lib/PublicInbox/MsgTime.pm             | 2 ++
 lib/PublicInbox/Reply.pm               | 2 ++
 lib/PublicInbox/SaPlugin/ListMirror.pm | 2 +-
 lib/PublicInbox/SearchIdxPart.pm       | 3 +++
 lib/PublicInbox/SearchMsg.pm           | 2 ++
 lib/PublicInbox/Spamcheck.pm           | 2 ++
 lib/PublicInbox/Spamcheck/Spamc.pm     | 2 ++
 lib/PublicInbox/SpawnPP.pm             | 3 +++
 lib/PublicInbox/V2Writable.pm          | 1 +
 lib/PublicInbox/WwwAtomStream.pm       | 3 +++
 lib/PublicInbox/WwwStream.pm           | 4 ++++
 lib/PublicInbox/WwwText.pm             | 1 +
 20 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/lib/PublicInbox/AltId.pm b/lib/PublicInbox/AltId.pm
index 4a6ff97..300bdc0 100644
--- a/lib/PublicInbox/AltId.pm
+++ b/lib/PublicInbox/AltId.pm
@@ -1,12 +1,21 @@
 # Copyright (C) 2016-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
+# Used for giving serial numbers to messages.  This can be tied to
+# the msgmap for live updates to living lists (see
+# PublicInbox::Filters::RubyLang), or kept separate for imports
+# of defunct NNTP groups (e.g. scripts/xhdr-num2mid)
+#
+# Introducing NEW uses of serial numbers is discouraged because of
+# it leads to reliance on centralization.  However, being able
+# to use existing serial numbers is beneficial.
 package PublicInbox::AltId;
 use strict;
 use warnings;
 use URI::Escape qw(uri_unescape);
 
 # spec: TYPE:PREFIX:param1=value1&param2=value2&...
+# The PREFIX will be a searchable boolean prefix in Xapian
 # Example: serial:gmane:file=/path/to/altmsgmap.sqlite3
 sub new {
 	my ($class, $inbox, $spec, $writable) = @_;
diff --git a/lib/PublicInbox/ContentId.pm b/lib/PublicInbox/ContentId.pm
index dd3155b..9baf0e7 100644
--- a/lib/PublicInbox/ContentId.pm
+++ b/lib/PublicInbox/ContentId.pm
@@ -1,6 +1,11 @@
 # Copyright (C) 2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
+# Unstable internal API.
+# Used for on-the-fly duplicate detection in V2 inboxes.
+# This is not stored in any database anywhere and may change
+# as changes in duplicate detection are needed.
+# See L<public-inbox-v2-format(5)> manpage for more details.
 package PublicInbox::ContentId;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/GetlineBody.pm b/lib/PublicInbox/GetlineBody.pm
index 7fcd7c0..ea07f3d 100644
--- a/lib/PublicInbox/GetlineBody.pm
+++ b/lib/PublicInbox/GetlineBody.pm
@@ -4,6 +4,10 @@
 # Wrap a pipe or file for PSGI streaming response bodies and calls the
 # end callback when the object goes out-of-scope.
 # This depends on rpipe being _blocking_ on getline.
+#
+# public-inbox-httpd favors "getline" response bodies to take a
+# "pull"-based approach to feeding slow clients (as opposed to a
+# more common "push" model)
 package PublicInbox::GetlineBody;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/GitHTTPBackend.pm b/lib/PublicInbox/GitHTTPBackend.pm
index 6efe5b3..54ccfa0 100644
--- a/lib/PublicInbox/GitHTTPBackend.pm
+++ b/lib/PublicInbox/GitHTTPBackend.pm
@@ -2,7 +2,7 @@
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
 # when no endpoints match, fallback to this and serve a static file
-# or smart HTTP
+# or smart HTTP.  This is our wrapper for git-http-backend(1)
 package PublicInbox::GitHTTPBackend;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/HTTPD.pm b/lib/PublicInbox/HTTPD.pm
index f923dbb..8cf365d 100644
--- a/lib/PublicInbox/HTTPD.pm
+++ b/lib/PublicInbox/HTTPD.pm
@@ -1,6 +1,8 @@
 # Copyright (C) 2016-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
+# wraps a listen socket for HTTP and links it to the PSGI app in
+# public-inbox-httpd
 package PublicInbox::HTTPD;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Import.pm b/lib/PublicInbox/Import.pm
index 29c482f..fd4255c 100644
--- a/lib/PublicInbox/Import.pm
+++ b/lib/PublicInbox/Import.pm
@@ -2,8 +2,9 @@
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 #
 # git fast-import-based ssoma-mda MDA replacement
-# This is only ever run by public-inbox-mda and public-inbox-learn,
-# not the WWW or NNTP code which only requires read-only access.
+# This is only ever run by public-inbox-mda, public-inbox-learn
+# and public-inbox-watch. Not the WWW or NNTP code which only
+# requires read-only access.
 package PublicInbox::Import;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Mbox.pm b/lib/PublicInbox/Mbox.pm
index 11b2302..78dbe27 100644
--- a/lib/PublicInbox/Mbox.pm
+++ b/lib/PublicInbox/Mbox.pm
@@ -1,8 +1,12 @@
 # Copyright (C) 2015-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
-# Streaming interface for formatting messages as an mboxrd.
-# Used by the web interface
+# Streaming (via getline) interface for formatting messages as an mboxrd.
+# Used by the PSGI web interface.
+#
+# public-inbox-httpd favors "getline" response bodies to take a
+# "pull"-based approach to feeding slow clients (as opposed to a
+# more common "push" model)
 package PublicInbox::Mbox;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/MsgIter.pm b/lib/PublicInbox/MsgIter.pm
index 9e2d797..eb94d62 100644
--- a/lib/PublicInbox/MsgIter.pm
+++ b/lib/PublicInbox/MsgIter.pm
@@ -1,6 +1,7 @@
 # Copyright (C) 2016-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
-#
+
+# read-only utilities for Email::MIME
 package PublicInbox::MsgIter;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/MsgTime.pm b/lib/PublicInbox/MsgTime.pm
index f3ebb64..6216023 100644
--- a/lib/PublicInbox/MsgTime.pm
+++ b/lib/PublicInbox/MsgTime.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+
+# Various date/time-related functions
 package PublicInbox::MsgTime;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Reply.pm b/lib/PublicInbox/Reply.pm
index 11e17ed..0f6dd83 100644
--- a/lib/PublicInbox/Reply.pm
+++ b/lib/PublicInbox/Reply.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2014-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+
+# For reply instructions and address generation in WWW UI
 package PublicInbox::Reply;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/SaPlugin/ListMirror.pm b/lib/PublicInbox/SaPlugin/ListMirror.pm
index f2071dd..31f926f 100644
--- a/lib/PublicInbox/SaPlugin/ListMirror.pm
+++ b/lib/PublicInbox/SaPlugin/ListMirror.pm
@@ -1,7 +1,7 @@
 # Copyright (C) 2016-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
-# Rules useful for running a mailing list mirror.  We want to:
+# SpamAssassin rules useful for running a mailing list mirror.  We want to:
 # * ensure Received: headers are really from the list mail server
 #   users expect.  This is to prevent malicious users from
 #   injecting spam into mirrors without going through the expected
diff --git a/lib/PublicInbox/SearchIdxPart.pm b/lib/PublicInbox/SearchIdxPart.pm
index 078d2df..7fe2120 100644
--- a/lib/PublicInbox/SearchIdxPart.pm
+++ b/lib/PublicInbox/SearchIdxPart.pm
@@ -1,5 +1,8 @@
 # Copyright (C) 2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+
+# used to interface with a single Xapian partition in V2 repos.
+# See L<public-inbox-v2-format(5)> for more info on how we partition Xapian
 package PublicInbox::SearchIdxPart;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/SearchMsg.pm b/lib/PublicInbox/SearchMsg.pm
index c7787ea..32cceb2 100644
--- a/lib/PublicInbox/SearchMsg.pm
+++ b/lib/PublicInbox/SearchMsg.pm
@@ -3,6 +3,8 @@
 # based on notmuch, but with no concept of folders, files or flags
 #
 # Wraps a document inside our Xapian search index.
+# There may be many of these objects loaded in memory at once
+# for large threads in our WWW UI.
 package PublicInbox::SearchMsg;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Spamcheck.pm b/lib/PublicInbox/Spamcheck.pm
index 062479d..54d54cb 100644
--- a/lib/PublicInbox/Spamcheck.pm
+++ b/lib/PublicInbox/Spamcheck.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+
+# Spamchecking used by -watch and -mda tools
 package PublicInbox::Spamcheck;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/Spamcheck/Spamc.pm b/lib/PublicInbox/Spamcheck/Spamc.pm
index a76e920..88aa531 100644
--- a/lib/PublicInbox/Spamcheck/Spamc.pm
+++ b/lib/PublicInbox/Spamcheck/Spamc.pm
@@ -1,5 +1,7 @@
 # Copyright (C) 2016-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+
+# Default spam filter class for wrapping spamc(1)
 package PublicInbox::Spamcheck::Spamc;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/SpawnPP.pm b/lib/PublicInbox/SpawnPP.pm
index d0df94d..743db22 100644
--- a/lib/PublicInbox/SpawnPP.pm
+++ b/lib/PublicInbox/SpawnPP.pm
@@ -1,5 +1,8 @@
 # Copyright (C) 2016-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+
+# Pure-Perl implementation of "spawn".  This can't take advantage
+# of vfork, so no speedups under Linux for spawning from large processes.
 package PublicInbox::SpawnPP;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/V2Writable.pm b/lib/PublicInbox/V2Writable.pm
index fbab8f7..222df5c 100644
--- a/lib/PublicInbox/V2Writable.pm
+++ b/lib/PublicInbox/V2Writable.pm
@@ -2,6 +2,7 @@
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
 # This interface wraps and mimics PublicInbox::Import
+# Used to write to V2 inboxes (see L<public-inbox-v2-format(5)>).
 package PublicInbox::V2Writable;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/WwwAtomStream.pm b/lib/PublicInbox/WwwAtomStream.pm
index 38eba2a..712c3dc 100644
--- a/lib/PublicInbox/WwwAtomStream.pm
+++ b/lib/PublicInbox/WwwAtomStream.pm
@@ -2,6 +2,9 @@
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 #
 # Atom body stream for which yields getline+close methods
+# public-inbox-httpd favors "getline" response bodies to take a
+# "pull"-based approach to feeding slow clients (as opposed to a
+# more common "push" model)
 package PublicInbox::WwwAtomStream;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/WwwStream.pm b/lib/PublicInbox/WwwStream.pm
index d39f551..e548f00 100644
--- a/lib/PublicInbox/WwwStream.pm
+++ b/lib/PublicInbox/WwwStream.pm
@@ -2,6 +2,10 @@
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 #
 # HTML body stream for which yields getline+close methods
+#
+# public-inbox-httpd favors "getline" response bodies to take a
+# "pull"-based approach to feeding slow clients (as opposed to a
+# more common "push" model)
 package PublicInbox::WwwStream;
 use strict;
 use warnings;
diff --git a/lib/PublicInbox/WwwText.pm b/lib/PublicInbox/WwwText.pm
index e6d00ea..b5874cf 100644
--- a/lib/PublicInbox/WwwText.pm
+++ b/lib/PublicInbox/WwwText.pm
@@ -1,6 +1,7 @@
 # Copyright (C) 2016-2018 all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
+# used for displaying help texts and other non-mail content
 package PublicInbox::WwwText;
 use strict;
 use warnings;
-- 
EW