From f564327fd1e694056a4b13ed398cabd8d0d4c173 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Fri, 20 Nov 2015 01:02:40 +0000 Subject: various internal documentation updates Hopefully this gives new hackers a better overview of how the components relate to each other. --- lib/PublicInbox/Config.pm | 2 ++ lib/PublicInbox/ExtMsg.pm | 5 +++++ lib/PublicInbox/Feed.pm | 2 ++ lib/PublicInbox/Filter.pm | 1 + lib/PublicInbox/GitCatFile.pm | 3 +++ lib/PublicInbox/Hval.pm | 3 ++- lib/PublicInbox/Listener.pm | 2 ++ lib/PublicInbox/MDA.pm | 2 ++ lib/PublicInbox/MID.pm | 2 ++ lib/PublicInbox/Mbox.pm | 4 +++- lib/PublicInbox/Msgmap.pm | 8 +++++++- lib/PublicInbox/NNTP.pm | 4 +++- lib/PublicInbox/NewsGroup.pm | 3 +++ lib/PublicInbox/Search.pm | 2 ++ lib/PublicInbox/SearchIdx.pm | 5 +++++ lib/PublicInbox/SearchMsg.pm | 2 ++ lib/PublicInbox/SearchView.pm | 2 ++ lib/PublicInbox/View.pm | 3 +++ lib/PublicInbox/WWW.pm | 2 ++ 19 files changed, 53 insertions(+), 4 deletions(-) (limited to 'lib/PublicInbox') 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 
 text content for GUIs
-- 
cgit v1.2.3-24-ge0c7