From: Eric Wong Date: Fri, 20 Nov 2015 01:02:40 +0000 (+0000) Subject: various internal documentation updates X-Git-Tag: v1.0.0~784 X-Git-Url: http://www.git.stargrave.org/?p=public-inbox.git;a=commitdiff_plain;h=f564327fd1e694056a4b13ed398cabd8d0d4c173 various internal documentation updates Hopefully this gives new hackers a better overview of how the components relate to each other. --- 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
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 
 # 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 
 # 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 
 # 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 
 # 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 
 # 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;