* [PATCH] various internal documentation updates
@ 2015-11-20 2:37 Eric Wong
0 siblings, 0 replies; only message in thread
From: Eric Wong @ 2015-11-20 2:37 UTC (permalink / raw)
To: meta
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 ++
public-inbox-init | 2 ++
public-inbox-learn | 3 +++
public-inbox-mda | 2 ++
public-inbox-nntpd | 2 ++
public-inbox.cgi | 2 ++
24 files changed, 64 insertions(+), 4 deletions(-)
diff --git a/lib/PublicInbox/Config.pm b/lib/PublicInbox/Config.pm
index 0d73a86..8da00b0 100644
--- a/lib/PublicInbox/Config.pm
+++ b/lib/PublicInbox/Config.pm
@@ -1,5 +1,7 @@
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# 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 0cba49d..5068047 100644
--- a/lib/PublicInbox/ExtMsg.pm
+++ b/lib/PublicInbox/ExtMsg.pm
@@ -1,5 +1,10 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 e66b678..1201dd1 100644
--- a/lib/PublicInbox/Feed.pm
+++ b/lib/PublicInbox/Feed.pm
@@ -1,5 +1,7 @@
# Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
# 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 82baa9b..ea6fd33 100644
--- a/lib/PublicInbox/Filter.pm
+++ b/lib/PublicInbox/Filter.pm
@@ -1,6 +1,7 @@
# Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
# 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 629d23e..dd95d5f 100644
--- a/lib/PublicInbox/GitCatFile.pm
+++ b/lib/PublicInbox/GitCatFile.pm
@@ -1,5 +1,8 @@
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# 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 9fbe616..ab6e044 100644
--- a/lib/PublicInbox/Hval.pm
+++ b/lib/PublicInbox/Hval.pm
@@ -1,7 +1,8 @@
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# 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 7f9658b..67817d9 100644
--- a/lib/PublicInbox/Listener.pm
+++ b/lib/PublicInbox/Listener.pm
@@ -1,5 +1,7 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 7025fb3..ba5f36b 100644
--- a/lib/PublicInbox/MDA.pm
+++ b/lib/PublicInbox/MDA.pm
@@ -1,5 +1,7 @@
# Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
# 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 3d404ef..169ffa7 100644
--- a/lib/PublicInbox/MID.pm
+++ b/lib/PublicInbox/MID.pm
@@ -1,5 +1,7 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 80e8efc..c180a0d 100644
--- a/lib/PublicInbox/Mbox.pm
+++ b/lib/PublicInbox/Mbox.pm
@@ -1,6 +1,8 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 6e9f274..8fe17a9 100644
--- a/lib/PublicInbox/Msgmap.pm
+++ b/lib/PublicInbox/Msgmap.pm
@@ -1,6 +1,12 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 0bfafa8..295aee0 100644
--- a/lib/PublicInbox/NNTP.pm
+++ b/lib/PublicInbox/NNTP.pm
@@ -1,5 +1,7 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 02e9011..3a31895 100644
--- a/lib/PublicInbox/NewsGroup.pm
+++ b/lib/PublicInbox/NewsGroup.pm
@@ -1,5 +1,8 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 fbc6882..0f7815f 100644
--- a/lib/PublicInbox/Search.pm
+++ b/lib/PublicInbox/Search.pm
@@ -1,6 +1,8 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 0646cfb..e9af547 100644
--- a/lib/PublicInbox/SearchIdx.pm
+++ b/lib/PublicInbox/SearchIdx.pm
@@ -1,6 +1,11 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 8d49ee2..93be747 100644
--- a/lib/PublicInbox/SearchMsg.pm
+++ b/lib/PublicInbox/SearchMsg.pm
@@ -1,6 +1,8 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 a51acbb..a15af55 100644
--- a/lib/PublicInbox/SearchView.pm
+++ b/lib/PublicInbox/SearchView.pm
@@ -1,5 +1,7 @@
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 92fedd1..15d846a 100644
--- a/lib/PublicInbox/View.pm
+++ b/lib/PublicInbox/View.pm
@@ -1,5 +1,8 @@
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# 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 fb57163..d00dfe7 100644
--- a/lib/PublicInbox/WWW.pm
+++ b/lib/PublicInbox/WWW.pm
@@ -1,6 +1,8 @@
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# 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 <pre> text content for GUIs
diff --git a/public-inbox-init b/public-inbox-init
index d6a6382..d66361d 100755
--- a/public-inbox-init
+++ b/public-inbox-init
@@ -1,6 +1,8 @@
#!/usr/bin/perl -w
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# 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 3b0dae8..0c7b419 100755
--- a/public-inbox-learn
+++ b/public-inbox-learn
@@ -1,6 +1,9 @@
#!/usr/bin/perl -w
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# 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 df8ca38..73c4ae1 100755
--- a/public-inbox-mda
+++ b/public-inbox-mda
@@ -1,6 +1,8 @@
#!/usr/bin/perl -w
# Copyright (C) 2013-2015 all contributors <meta@public-inbox.org>
# 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 0035637..1f0cd37 100755
--- a/public-inbox-nntpd
+++ b/public-inbox-nntpd
@@ -1,6 +1,8 @@
#!/usr/bin/perl -w
# Copyright (C) 2015 all contributors <meta@public-inbox.org>
# 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 157cf6a..4b74a62 100755
--- a/public-inbox.cgi
+++ b/public-inbox.cgi
@@ -1,6 +1,8 @@
#!/usr/bin/perl -w
# Copyright (C) 2014-2015 all contributors <meta@public-inbox.org>
# 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;
--
EW
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2015-11-20 2:37 UTC | newest]
Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-11-20 2:37 [PATCH] various internal documentation updates Eric Wong
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).