[pkgsrc/trunk]: pkgsrc/pkgtools/pbulk/files/pbulk/pbuild Added some comments ...

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/1e77f6135d28
branches:  trunk
changeset: 535761:1e77f6135d28
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Wed Nov 28 11:34:20 2007 +0000

description:
Added some comments that explain the data structures.

diffstat:

 pkgtools/pbulk/files/pbulk/pbuild/jobs.c   |   8 +++++-
 pkgtools/pbulk/files/pbulk/pbuild/pbuild.h |  39 +++++++++++++++++++++++++++++-
 2 files changed, 45 insertions(+), 2 deletions(-)

diffs (90 lines):

diff -r 5e2584805b7e -r 1e77f6135d28 pkgtools/pbulk/files/pbulk/pbuild/jobs.c
--- a/pkgtools/pbulk/files/pbulk/pbuild/jobs.c  Wed Nov 28 09:18:57 2007 +0000
+++ b/pkgtools/pbulk/files/pbulk/pbuild/jobs.c  Wed Nov 28 11:34:20 2007 +0000
@@ -1,4 +1,4 @@
-/* $NetBSD: jobs.c,v 1.5 2007/08/15 20:55:28 joerg Exp $ */
+/* $NetBSD: jobs.c,v 1.6 2007/11/28 11:34:20 rillig Exp $ */
 
 /*-
  * Copyright (c) 2007 Joerg Sonnenberger <joerg%NetBSD.org@localhost>.
@@ -391,6 +391,12 @@
        }       
 }
 
+/**
+ * Changes the state of the ''job'' to ''state'' and runs some code
+ * depending on the new state. If ''log_state'' is non-zero, the package
+ * name is written to either the "error" or the "success" log, depending
+ * on the ''state''.
+ */
 void
 process_job(struct build_job *job, enum job_state state, int log_state)
 {
diff -r 5e2584805b7e -r 1e77f6135d28 pkgtools/pbulk/files/pbulk/pbuild/pbuild.h
--- a/pkgtools/pbulk/files/pbulk/pbuild/pbuild.h        Wed Nov 28 09:18:57 2007 +0000
+++ b/pkgtools/pbulk/files/pbulk/pbuild/pbuild.h        Wed Nov 28 11:34:20 2007 +0000
@@ -1,4 +1,4 @@
-/* $NetBSD: pbuild.h,v 1.3 2007/07/21 15:44:02 tnn Exp $ */
+/* $NetBSD: pbuild.h,v 1.4 2007/11/28 11:34:20 rillig Exp $ */
 
 /*-
  * Copyright (c) 2007 Joerg Sonnenberger <joerg%NetBSD.org@localhost>.
@@ -36,6 +36,21 @@
 #include <inttypes.h>
 #endif
 
+/**
+ * At the very beginning of a pbulk, each job is in state JOB_INIT.
+ *
+ * (jobs.c, init_jobs:) If scanning the package failed or the package is
+ * not available for this configuration, its state is changed to
+ * JOB_PREFAILED. Packages that are listed in the "error" log are marked
+ * as JOB_FAILED, those in the the "success" log are marked as JOB_DONE.
+ * The remaining jobs are marked as JOB_OPEN.
+ *
+ * The packages that are ready to be built are those that have the state
+ * JOB_OPEN and no pending dependencies. At most one job can be in the
+ * state JOB_IN_PROCESSING. After trying to build a job, its state is
+ * set to either JOB_DONE or to JOB_FAILED. In the latter case, all the
+ * jobs that depend on this one are marked as JOB_INDIRECT_FAILED.
+ */
 enum job_state {
        JOB_INIT,
        JOB_OPEN,
@@ -65,14 +80,36 @@
 };
 
 struct build_job {
+       /** The package name, including the version number. */
        char *pkgname;
+
+       /**
+        * Pointers into the output from pbulk-resolve. The lines
+        * between these two pointers describe additional properties
+        * of the job, such as the PKGPATH in which to build the
+        * package. The information can be accessed with the
+        * find_content function.
+        */
        const char *begin;
        const char *end;
+
        enum job_state state;
        int pkg_depth;
+
+       /**
+        * Iff this is 1, this package and all its dependencies do not
+        * have any definition for RESTRICTED or NO_BIN_ON_FTP, and thus
+        * may be uploaded on a public FTP server.
+        */
        int unrestricted_subset;
+
+       /**
+        * The number of direct dependencies that must be built before
+        * this package can be tried.
+        */
        size_t open_depends;
 
+       /** The packages that depend on this package. */
        SLIST_HEAD(, dependency_list) depending_pkgs;
 
        TAILQ_ENTRY(build_job) build_link;