about summary refs log tree commit homepage
diff options
context:
space:
mode:
-rw-r--r--lib/PublicInbox/AltId.pm9
-rw-r--r--lib/PublicInbox/ContentId.pm5
-rw-r--r--lib/PublicInbox/GetlineBody.pm4
-rw-r--r--lib/PublicInbox/GitHTTPBackend.pm2
-rw-r--r--lib/PublicInbox/HTTPD.pm2
-rw-r--r--lib/PublicInbox/Import.pm5
-rw-r--r--lib/PublicInbox/Mbox.pm8
-rw-r--r--lib/PublicInbox/MsgIter.pm3
-rw-r--r--lib/PublicInbox/MsgTime.pm2
-rw-r--r--lib/PublicInbox/Reply.pm2
-rw-r--r--lib/PublicInbox/SaPlugin/ListMirror.pm2
-rw-r--r--lib/PublicInbox/SearchIdxPart.pm3
-rw-r--r--lib/PublicInbox/SearchMsg.pm2
-rw-r--r--lib/PublicInbox/Spamcheck.pm2
-rw-r--r--lib/PublicInbox/Spamcheck/Spamc.pm2
-rw-r--r--lib/PublicInbox/SpawnPP.pm3
-rw-r--r--lib/PublicInbox/V2Writable.pm1
-rw-r--r--lib/PublicInbox/WwwAtomStream.pm3
-rw-r--r--lib/PublicInbox/WwwStream.pm4
-rw-r--r--lib/PublicInbox/WwwText.pm1
20 files changed, 58 insertions, 7 deletions
diff --git a/lib/PublicInbox/AltId.pm b/lib/PublicInbox/AltId.pm
index 4a6ff97c..300bdc0b 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 dd3155be..9baf0e76 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 7fcd7c03..ea07f3d6 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 6efe5b31..54ccfa05 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 f923dbb6..8cf365d0 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 29c482f9..fd4255cf 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 11b23022..78dbe27e 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 9e2d797f..eb94d621 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 f3ebb644..62160233 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 11e17ede..0f6dd83b 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 f2071dd5..31f926fa 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 078d2df1..7fe2120a 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 c7787ea1..32cceb25 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 062479d6..54d54cbc 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 a76e920f..88aa5315 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 d0df94d0..743db224 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 fbab8f70..222df5c2 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 38eba2a0..712c3dc8 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 d39f5511..e548f00f 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 e6d00ea9..b5874cf6 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;