From a9cab9c477b74b3b828c26aa64e70d88c9d6744c Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Mon, 7 Jan 2019 09:09:51 +0000 Subject: doc: various overview-level module comments 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 4a6ff97c..300bdc0b 100644 --- a/lib/PublicInbox/AltId.pm +++ b/lib/PublicInbox/AltId.pm @@ -1,12 +1,21 @@ # Copyright (C) 2016-2018 all contributors # License: AGPL-3.0+ +# 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¶m2=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 # License: AGPL-3.0+ +# 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 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+ # 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 # License: AGPL-3.0+ +# 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+ # # 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 # License: AGPL-3.0+ -# 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 # License: AGPL-3.0+ -# + +# 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 # License: AGPL-3.0+ + +# 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 # License: AGPL-3.0+ + +# 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 # License: AGPL-3.0+ -# 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 # License: AGPL-3.0+ + +# used to interface with a single Xapian partition in V2 repos. +# See L 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 # License: AGPL-3.0+ + +# 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 # License: AGPL-3.0+ + +# 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 # License: AGPL-3.0+ + +# 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+ # This interface wraps and mimics PublicInbox::Import +# Used to write to V2 inboxes (see L). 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+ # # 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+ # # 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 # License: AGPL-3.0+ +# used for displaying help texts and other non-mail content package PublicInbox::WwwText; use strict; use warnings; -- cgit v1.2.3-24-ge0c7