--- a/ProjectDefinition.st	Tue Nov 11 11:23:47 2014 +0100
+++ b/ProjectDefinition.st	Tue Nov 11 12:15:04 2014 +0100
@@ -72,21 +72,33 @@
 documentation
 "
     As ST/X is (still) very tightly bound with stc, we keep the package and project information
-    in a class-object (instead of some Project-object). This has the advantage, that it can be
-    compiled and included in a compiled class library just like any other class.
-    Every package includes an subclass of me (an instance of my meta), which provides useful
-    information about the versioning and packaging. Me myself, I know how to generate dependency
-    information and can generate makefiles and other build-support files for compilation.
+    in a class-object (instead of some project object) and all queries about package contents and 
+    attributes are implemented as class methods. 
+    This has the advantage, that it can be compiled and included in a compiled class library just like any other class.
+    Every package includes a subclass of me (an instance of my meta), which provides useful
+    information about the versioning and packaging. 
+    Me myself, I know how to generate dependency information and can generate makefiles and other build-support 
+    files for compilation (see the browser's 'Checkin Build Support File' menu item..
+
+    When a package is loaded from a binary shared class lib (i.e. a compiled class library is loaded
+    via 'Smalltalk loadPackage:'), the loading is done in multiple phases:
+        1) the shared object is loaded, but not installed (registered) in Smalltalk
+        2) the ProjectDefinition class is registered and initialized.
+        3) the ProjectDefinition class is asked to load its prerequisites. This may lead to other packages
+           to be loaded - either as binary class libraries or from source, whichever is found.
+        4) the remaining classes and extensions are registered
 
     Some special notes about extension methods:
-    if a package is loaded (Smalltalk loadPackage:'foo:bar/baz'), any already loaded package of which
-    methods are overwritten by an extension of this package, the other package is asked to safe those
-    methods in its safe(ForOverwrittenMethods). Thus, if the other package or any of its classes is asked
-    to file itself out, it can do so using the safe (otherwise, you'D not be able to checkin a class while
-    it has an overriding extension loaded).
-    Also, the information about which other package was in charge when a method is overwritten is recorded in
-    extensionOverwriteInfo. This is used to correctly reinstall an overwritten method, whenever a package is
-    unloaded.
+      if a package is loaded (Smalltalk loadPackage:'foo:bar/baz'), any already loaded package of which
+      methods are overwritten by an extension method of the loaded package, the other package is asked to safe those
+      methods in its safe(ForOverwrittenMethods). 
+      Thus, if the other package or any of its classes is asked
+      to file itself out, it can do so using the safe (otherwise, you'd not be able to check the original class into
+      its repository while it has an overriding extension loaded).
+
+      Also, the information about which other package was in charge when a method is overwritten is recorded in
+      extensionOverwriteInfo. 
+      This is used to correctly reinstall an overwritten method, whenever a package is unloaded.
 
 "
 ! !
@@ -135,8 +147,16 @@
 !
 
 definitionClassForPackage:aPackageID
+    "given a packageID (such as 'stx:libfoo/bar'), lookup the corresponding peoject definition class.
+     Return it, or nil if not present"
+
     ^ self definitionClassForPackage:aPackageID createIfAbsent:false
 
+    "
+     ProjectDefinition definitionClassForPackage:'stx:libbasic'
+     ProjectDefinition definitionClassForPackage:'stx:libfoobarBaz'
+    "
+
     "Modified: / 17-08-2006 / 14:33:35 / cg"
 !
 
@@ -753,7 +773,6 @@
 
 
 
-
 !ProjectDefinition class methodsFor:'accessing - packaging'!
 
 classNames:aCollectionOfClassNames
@@ -1016,7 +1035,6 @@
         ].
 ! !
 
-
 !ProjectDefinition class methodsFor:'accessing - tests'!
 
 excludedFromTestSuite
@@ -2484,7 +2502,6 @@
     "Created: / 18-08-2006 / 12:51:38 / cg"
 ! !
 
-
 !ProjectDefinition class methodsFor:'description - project information'!
 
 applicationAdditionalIconFileNames
@@ -7624,11 +7641,11 @@
 !ProjectDefinition class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic/ProjectDefinition.st,v 1.518 2014-11-01 00:26:17 vrany Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/ProjectDefinition.st,v 1.519 2014-11-11 11:15:04 cg Exp $'
 !
 
 version_CVS
-    ^ '$Header: /cvs/stx/stx/libbasic/ProjectDefinition.st,v 1.518 2014-11-01 00:26:17 vrany Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/ProjectDefinition.st,v 1.519 2014-11-11 11:15:04 cg Exp $'
 !
 
 version_SVN