Index: modules/system/system.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.module,v
retrieving revision 1.341
diff -u -F^f -r1.341 system.module
--- modules/system/system.module	10 Aug 2006 15:42:33 -0000	1.341
+++ modules/system/system.module	13 Aug 2006 03:15:05 -0000
@@ -943,11 +943,11 @@ function system_default_region($theme) {
 
 /**
  * Returns an array of files objects of the given type from the site-wide
- * directory (i.e. modules/), the all-sites directory (i.e. sites/all/modules/)
- * and site-specific directory (i. e. sites/somesite/modules/). The returned
- * array will be keyed using the key specified (name, basename, filename). Using
- * name or basename will cause site- specific files to shadow files in the
- * default directories. That is, if a file with the same name appears in both
+ * directory (i.e. modules/), the all-sites directory (i.e. sites/all/modules/),
+ * the profiles directory, and site-specific directory (i. e. sites/somesite/modules/). 
+ * The returned array will be keyed using the key specified (name, basename, filename).
+ * Using name or basename will cause site-specific files to be prioritized over similar 
+ * files in the default directories. That is, if a file with the same name appears in both
  * the site-wide directory and site-specific directory, only the site-specific
  * version will be included.
  *
@@ -974,6 +974,9 @@ function system_listing($mask, $director
   // Always search sites/all/* as well as the global directories
   $searchdir[] = 'sites/all';
 
+  // the 'profiles' directory contains pristine collections of modules and themes as organized by a distribution.
+  // it is pristine in the same way that /modules is pristine for core; users should avoid changing anything there
+  // in favor of sites/all or sites/<domain> directories.
   if (file_exists("profiles/$profile/$directory")) {
     $searchdir[] = "profiles/$profile/$directory";
   }