document what's going on...

2 files changed, 37 insertions, 5 deletions

diff --git a/usr.sbin/pkg_add/OpenBSD/Tracker.pm b/usr.sbin/pkg_add/OpenBSD/Tracker.pm
index 117c1190878..a5c35e69688 100644
--- a/usr.sbin/pkg_add/OpenBSD/Tracker.pm
+++ b/usr.sbin/pkg_add/OpenBSD/Tracker.pm
@@ -1,5 +1,5 @@
 # ex:ts=8 sw=4:
-# $OpenBSD: Tracker.pm,v 1.6 2009/11/08 10:46:11 espie Exp $
+# $OpenBSD: Tracker.pm,v 1.7 2009/11/10 10:28:12 espie Exp $
 #
 # Copyright (c) 2009 Marc Espie <espie@openbsd.org>
 #
@@ -18,9 +18,19 @@
 use strict;
 use warnings;
 
-# the tracker class is used to track what's going on during a complicated
-# install. Specifically: what packages are installed, what's left to do,
-# etc
+# In order to deal with dependencies, we have to know what's actually installed,
+# and what can actually be updated.
+# Specifically, to solve a dependency:
+# - look at packages to_install
+# - look at installed packages
+#   - if it's marked to_update, then we must process the update first
+#   - if it's marked as installed, or as cant_update, or uptodate, then
+#   we can use the installed packages.
+#   - otherwise, in update mode, put a request to update the package (e.g.,
+#   create a new UpdateSet.
+
+# the Tracker object does maintain that information globally so that 
+# Update/Dependencies can do its job.
 
 package OpenBSD::Tracker;
 sub new
diff --git a/usr.sbin/pkg_add/OpenBSD/UpdateSet.pm b/usr.sbin/pkg_add/OpenBSD/UpdateSet.pm
index 8fa80d0aeec..e326bf8e643 100644
--- a/usr.sbin/pkg_add/OpenBSD/UpdateSet.pm
+++ b/usr.sbin/pkg_add/OpenBSD/UpdateSet.pm
@@ -1,5 +1,5 @@
 # ex:ts=8 sw=4:
-# $OpenBSD: UpdateSet.pm,v 1.12 2009/11/08 10:46:11 espie Exp $
+# $OpenBSD: UpdateSet.pm,v 1.13 2009/11/10 10:28:12 espie Exp $
 #
 # Copyright (c) 2007 Marc Espie <espie@openbsd.org>
 #
@@ -15,6 +15,10 @@
 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
+
+# these things don't really live here, they're just stuff that's shared
+# between pkg_add and pkg_delete, so to avoid yes another header...
+
 package OpenBSD::SharedItemsRecorder;
 sub new
 {
@@ -48,6 +52,7 @@ sub progress
 	return $self->{progressmeter};
 }
 
+# we always have a progressmeter we can print to...
 sub setup_progressmeter
 {
 	my ($self, $opt_x) = @_;
@@ -96,6 +101,7 @@ sub choose_location
 	}
 }
 
+# stub class when no actual progressmeter that still prints out.
 package OpenBSD::StubProgress;
 sub clear {}
 
@@ -113,6 +119,22 @@ sub print
 	print STDERR @_;
 }
 
+# an UpdateSet is a list of packages to remove/install.
+# it contains three things:
+# -> a list of older packages to remove (installed locations)
+# -> a list of newer packages to add (might be very simple locations)
+# -> a list of "hints", as package names to install
+# every add/remove operations manipulate UpdateSet.
+#
+# Since older packages are always installed, they're organized as a hash.
+#
+# XXX: an UpdateSet succeeds or fails "together".
+# if several packages should be removed/added, then not being able
+# to do stuff on ONE of them is enough to invalidate the whole set.
+#
+# Normal UpdateSets contain one newer package at most.
+# Bigger UpdateSets can be created through the merge operation, which
+# will be used only when necessary.
 package OpenBSD::UpdateSet;
 sub new
 {