Index: libraries.api.php
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/libraries.api.php,v
retrieving revision 1.2
diff -u -p -r1.2 libraries.api.php
--- libraries.api.php	23 Jul 2010 12:57:01 -0000	1.2
+++ libraries.api.php	28 Aug 2010 15:56:56 -0000
@@ -21,17 +21,21 @@
  *     actual library. Only required if the extracted download package contains
  *     the actual library files in a sub-directory.
  *   - version callback: (optional) The name of a function that detects and
- *     returns the full version string of the library. Defaults to
- *     libraries_get_version(). The first argument is always $library, an array
- *     containing all library information as described here. The following
- *     argument(s) can either be:
- *     - options: An associative array of additional information to pass to the
- *       version callback. In this case the version arguments (see below) must
- *       be declared as an associative array.
- *     - or any number of independent arguments. In this case the version
- *       arguments (see below) must be declared as an indexed array.
+ *     returns the full version string of the library. The first argument is
+ *     always $library, an array containing all library information as described
+ *     here. There are two ways to declare the version callback's additional
+ *     arguments, either as a single $options parameter or as multiple
+ *     parameters, which correspond to the two ways to specify the argument
+ *     values (see 'version arguments'). Defaults to libraries_get_version().
  *   - version arguments: A list of arguments to pass to the version callback.
- *     The default version callback libraries_get_version() expects a single,
+ *     Version arguments can be declared either as an associative array whose
+ *     keys are the argument names or as an indexed array without specifying
+ *     keys. If declared as an associative array, the arguments get passed to
+ *     the version callback as a single $options parameter whose keys are the
+ *     argument names (i.e. $options is identical to the specified array). If
+ *     declared as an indexed array, the array values get passed to the version
+ *     callback as seperate arguments in the order they were declared. The
+ *     default version callback libraries_get_version() expects a single,
  *     associative array with named keys:
  *     - file: The filename to parse for the version, relative to the library
  *       path. For example: 'docs/changelog.txt'.
@@ -59,17 +63,21 @@
  *     - variant callback: (optional) The name of a function that detects
  *       returns TRUE or FALSE, depending on whether the variant is available or
  *       not. The first argument is always $library, an array containing all
- *       library information as described here. The seconds argument is always
- *       $name, a string containing the name of the variant. The following 
- *       argument(s) can either be:
- *       - options: An associative array of additional information to pass to
- *         the version callback. In this case the version arguments (see below)
- *         must be declared as an associative array.
- *       - or any number of independent arguments. In this case the version
- *         arguments (see below) must be declared as an indexed array.
- *       If ommitted, the variant is expected to always be available. Variants
- *       can be version specific.
+ *       library information as described here. The second is always a string
+ *       containing the variant name. There are two ways to declare the variant
+ *       callback's additinal arguments, either as a single $options parameter
+ *       or as multiple parameters, which correspond to the two ways to specify
+ *       the argument values (see 'variant arguments'). If ommitted, the variant
+ *       is expected to always be available.
  *     - variant arguments: A list of arguments to pass to the variant callback.
+ *       Variant arguments can be declared either as an associative array whose
+ *       keys are the argument names or as an indexed array without specifying
+ *       keys. If declared as an associative array, the arguments get passed to
+ *       the variant callback as a single $options parameter whose keys are the
+ *       argument names (i.e. $options is identical to the specified array). If
+ *       declared as an indexed array, the array values get passed to the
+ *       variant callback as seperate arguments in the order they were declared.
+ *     Variants can be version specific.
  *   - versions: (optional) An associative array of supported library versions.
  *     Naturally, external libraries evolve over time and so do their APIs. In
  *     case a library changes between versions, different 'files' may need to be
Index: tests/libraries_test.js
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/libraries_test.js,v
retrieving revision 1.2
diff -u -p -r1.2 libraries_test.js
--- tests/libraries_test.js	23 Jul 2010 12:57:01 -0000	1.2
+++ tests/libraries_test.js	28 Aug 2010 15:56:56 -0000
@@ -16,4 +16,4 @@ Drupal.behaviors.librariesTest = {
   }
 };
 
-})(jQuery); 
+})(jQuery);
Index: tests/libraries_test.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/libraries_test.module,v
retrieving revision 1.2
diff -u -p -r1.2 libraries_test.module
--- tests/libraries_test.module	23 Jul 2010 12:57:01 -0000	1.2
+++ tests/libraries_test.module	28 Aug 2010 15:56:56 -0000
@@ -8,24 +8,23 @@
 
 /**
  * Implements hook_libraries_info().
- *
- * Note: DO NOT use drupal_get_path() in your implementations! Used for testing
- * purposes only. It is strongly discouraged to declare the 'library path'
- * property as that will be detected by Libraries API automatically.
  */
 function libraries_test_libraries_info() {
   // Test library detection.
   $libraries['example_missing'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/missing',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('1'),
   );
   $libraries['example_undetected_version'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array(FALSE),
   );
   $libraries['example_unsupported_version'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('1'),
@@ -35,6 +34,7 @@ function libraries_test_libraries_info()
   );
 
   $libraries['example_supported_version'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('2'),
@@ -45,6 +45,7 @@ function libraries_test_libraries_info()
 
   // Test the default version callback.
   $libraries['example_default_version_callback'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
     'version arguments' => array(
       'file' => 'example_installed.txt',
@@ -56,6 +57,7 @@ function libraries_test_libraries_info()
 
   // Test a multiple-parameter version callback.
   $libraries['example_multiple_parameter_version_callback'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
     // Version 2
     'version callback' => '_libraries_get_version',
@@ -64,6 +66,7 @@ function libraries_test_libraries_info()
 
   // Test a top-level files property.
   $libraries['example_simple'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('1'),
@@ -84,6 +87,7 @@ function libraries_test_libraries_info()
   // Normally added by the corresponding module via hook_libraries_info_alter(),
   // these files should be automatically loaded when the library is loaded.
   $libraries['example_integration_files'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('2'),
@@ -104,6 +108,7 @@ function libraries_test_libraries_info()
 
   // Test version overloading.
   $libraries['example_versions'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('2'),
@@ -139,6 +144,7 @@ function libraries_test_libraries_info()
 
   // Test variant detection.
   $libraries['example_variant_missing'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('2'),
@@ -155,13 +161,14 @@ function libraries_test_libraries_info()
             'example_installed_variant_1.php',
           ),
         ),
-        'variant callback' => '_libraries_test_detect_variant',
+        'variant callback' => '_libraries_test_return_installed',
         'variant arguments' => array(FALSE),
       ),
     ),
   );
 
   $libraries['example_variant'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('2'),
@@ -178,7 +185,7 @@ function libraries_test_libraries_info()
             'example_installed_variant_1.php',
           ),
         ),
-        'variant callback' => '_libraries_test_detect_variant',
+        'variant callback' => '_libraries_test_return_installed',
         'variant arguments' => array(TRUE),
       ),
       'example_variant_2' => array(
@@ -193,7 +200,7 @@ function libraries_test_libraries_info()
             'example_installed_variant_2.php',
           ),
         ),
-        'variant callback' => '_libraries_test_detect_variant',
+        'variant callback' => '_libraries_test_return_installed',
         'variant arguments' => array(TRUE),
       ),
     ),
@@ -201,6 +208,7 @@ function libraries_test_libraries_info()
 
   // Test correct behaviour with multiple versions and multiple variants.
   $libraries['example_versions_and_variants'] = array(
+    // Never declare library path manually. It is detected automatically.
     'library path' => drupal_get_path('module', 'libraries') . '/tests/example',
     'version callback' => '_libraries_test_return_version',
     'version arguments' => array('2'),
@@ -219,7 +227,7 @@ function libraries_test_libraries_info()
                 'example_installed_1.php',
               ),
             ),
-            'variant callback' => '_libraries_test_detect_variant',
+            'variant callback' => '_libraries_test_return_installed',
             'variant arguments' => array(TRUE),
           ),
           'example_variant_2' => array(
@@ -234,7 +242,7 @@ function libraries_test_libraries_info()
                 'example_installed_variant_1.php',
               ),
             ),
-            'variant callback' => '_libraries_test_detect_variant',
+            'variant callback' => '_libraries_test_return_installed',
             'variant arguments' => array(TRUE),
           ),
         ),
@@ -253,7 +261,7 @@ function libraries_test_libraries_info()
                 'example_installed_2.php',
               ),
             ),
-            'variant callback' => '_libraries_test_detect_variant',
+            'variant callback' => '_libraries_test_return_installed',
             'variant arguments' => array(TRUE),
           ),
           'example_variant_2' => array(
@@ -268,7 +276,7 @@ function libraries_test_libraries_info()
                 'example_installed_variant_2.php',
               ),
             ),
-            'variant callback' => '_libraries_test_detect_variant',
+            'variant callback' => '_libraries_test_return_installed',
             'variant arguments' => array(TRUE),
           ),
         ),
@@ -282,8 +290,9 @@ function libraries_test_libraries_info()
 /**
  * Gets the version of an example library.
  *
- * Returns exactly the version string entered as the $version parameter, unless
- * you specify 'undetected', in which case it returns nothing.
+ * Returns exactly the version string entered as the $version parameter. This
+ * function cannot be collapsed with _libraries_test_return_installed(), because
+ * of the different arguments that are passed automatically.
  */
 function _libraries_test_return_version($library, $version) {
   return $version;
@@ -292,9 +301,11 @@ function _libraries_test_return_version(
 /**
  * Gets the version information from an arbitrary library.
  *
- * This is an exact copy of libraries_get_version() except for the fact that it
- * does not take a single associative array as a parameter but multiple
- * parameters. Since we support both type of version callbacks this might be
+ * Test function for a version callback with multiple arguments. This is an
+ * exact copy of libraries_get_version(), which uses a single $option argument,
+ * except for the fact that it uses multiple arguments. Since we support both
+ * type of version callbacks, detecting the version of a test library with this
+ * ensures that the arguments are passed correctly. This function might be
  * a useful reference for a custom version callback that uses multiple
  * parameters
  *
@@ -319,7 +330,7 @@ function _libraries_test_return_version(
  *
  * @see libraries_get_version()
  */
-function _libraries_get_version($library, $file, $pattern, $lines = 20, $cols = 200) {
+function _libraries_test_get_version($library, $file, $pattern, $lines = 20, $cols = 200) {
 
   $file = DRUPAL_ROOT . '/' . $library['library path'] . '/' . $file;
   if (!file_exists($file)) {
@@ -339,11 +350,12 @@ function _libraries_get_version($library
 /**
  * Detects the variant of an example library.
  *
- * Returns TRUE or FALSE depending on whether the $status parameter is 'missing'
- * or 'found'.
+ * Returns exactly the value of $installed, either TRUE or FALSE. This function
+ * cannot be collapsed with _libraries_test_return_installed(), because of the
+ * different arguments that are passed automatically.
  */
-function _libraries_test_detect_variant($library, $name, $status) {
-  return $status;
+function _libraries_test_return_installed($library, $name, $installed) {
+  return $installed;
 }
 
 /**
Index: tests/example/README.txt
===================================================================
RCS file: tests/example/README.txt
diff -N tests/example/README.txt
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ tests/example/README.txt	28 Aug 2010 15:56:56 -0000
@@ -0,0 +1,34 @@
+; $Id: example_installed.txt,v 1.2 2010/07/23 12:57:01 tstoeckler Exp $
+
+Example library
+
+Version 2
+
+This file is an example file to test version detection.
+
+The various other files in this directory are to test the loading of JavaScript,
+CSS and PHP files.
+- JavaScript: The JavaScript files, if loaded, insert a div with the id
+  'libraries-test' after the page title and put some sample text in it of the
+  form: "If this text shows up, the JavaScript file was loaded successfully. If
+  this text is [color], the CSS file was loaded successfully." [color] is either
+  'red', 'green', 'orange' or 'blue' (see below). This cannot be validated
+  programatically with SimpleTest. If you enable SimpleTest's verbose mode,
+  though, and see the above text in one of the debug pages, a JavaScript file
+  was loaded successfully. Which version and variant the JavaScript file belongs
+  depends on the color that is mentioned in the text (see below).
+- CSS: The CSS files, if loaded, make the text that was inserted via JavaScipt
+  (see above) a certain color. This cannot be validated
+  programatically with SimpleTest. If you enable SimpleTest's verbose mode,
+  though, and see the above text in a certain color (i.e. not in black), a CSS
+  file was loaded successfully. Which version and variant the CSS file belongs
+  to depends on the color:
+  - example_installed_1: red
+  - example_installed_2: green
+  - example_installed_variant_1: orange
+  - example_installed_variant_2: blue
+  Note that, because the CSS affects a div that is inserted via JavaScript, the
+  testing of CSS loading with this method is dependent on JavaScript loading.
+- PHP: The loading of PHP files is tested by defining a dummy function in the
+  PHP files and then checking whether this function was defined using
+  function_exists(). This can be checked programatically with SimpleTest.
Index: tests/example/example_installed_1.css
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/example/example_installed_1.css,v
retrieving revision 1.1
diff -u -p -r1.1 example_installed_1.css
--- tests/example/example_installed_1.css	23 Jul 2010 12:57:01 -0000	1.1
+++ tests/example/example_installed_1.css	28 Aug 2010 15:56:56 -0000
@@ -4,10 +4,8 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Because we cannot test CSS programatically with SimpleTest, the CSS below can
- * be useful for debugging with SimpleTest's verbose mode. Note that since the
- * DOM cannot be manipulated via CSS, JavaScript loading needs to be functional
- * for this to have any visible effect.
+ * Color the 'libraries-test' div red. See example_installed.txt for more
+ * information.
  */
 
 div#libraries-test {
Index: tests/example/example_installed_1.js
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/example/example_installed_1.js,v
retrieving revision 1.1
diff -u -p -r1.1 example_installed_1.js
--- tests/example/example_installed_1.js	23 Jul 2010 12:57:01 -0000	1.1
+++ tests/example/example_installed_1.js	28 Aug 2010 15:56:56 -0000
@@ -4,11 +4,11 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Because we cannot test JavaScript programatically with SimpleTest, the
- * JavaScript below can be useful for debugging with SimpleTest's verbose mode.
+ * Insert a 'libraries-test' div and some text below the page title. See
+ * example_installed.txt for more information.
  */
 
-(function ($) { 
+(function ($) {
 
 Drupal.behaviors.librariesTest = {
   attach: function(context, settings) {
@@ -16,4 +16,4 @@ Drupal.behaviors.librariesTest = {
   }
 };
 
-})(jQuery); 
+})(jQuery);
Index: tests/example/example_installed_2.css
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/example/example_installed_2.css,v
retrieving revision 1.2
diff -u -p -r1.2 example_installed_2.css
--- tests/example/example_installed_2.css	23 Jul 2010 12:57:01 -0000	1.2
+++ tests/example/example_installed_2.css	28 Aug 2010 15:56:56 -0000
@@ -4,10 +4,8 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Because we cannot test CSS programatically with SimpleTest, the CSS below can
- * be useful for debugging with SimpleTest's verbose mode. Note that since the
- * DOM cannot be manipulated via CSS, JavaScript loading needs to be functional
- * for this to have any visible effect.
+ * Color the 'libraries-test' div green. See example_installed.txt for more
+ * information.
  */
 
 div#libraries-test {
Index: tests/example/example_installed_2.js
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/example/example_installed_2.js,v
retrieving revision 1.2
diff -u -p -r1.2 example_installed_2.js
--- tests/example/example_installed_2.js	23 Jul 2010 12:57:01 -0000	1.2
+++ tests/example/example_installed_2.js	28 Aug 2010 15:56:56 -0000
@@ -4,8 +4,8 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Because we cannot test JavaScript programatically with SimpleTest, the
- * JavaScript below can be useful for debugging with SimpleTest's verbose mode.
+ * Insert a 'libraries-test' div and some text below the page title. See
+ * example_installed.txt for more information.
  */
 
 (function ($) {
@@ -16,4 +16,4 @@ Drupal.behaviors.librariesTest = {
   }
 };
 
-})(jQuery); 
+})(jQuery);
Index: tests/example/example_installed_variant_1.css
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/example/example_installed_variant_1.css,v
retrieving revision 1.1
diff -u -p -r1.1 example_installed_variant_1.css
--- tests/example/example_installed_variant_1.css	23 Jul 2010 12:57:01 -0000	1.1
+++ tests/example/example_installed_variant_1.css	28 Aug 2010 15:56:56 -0000
@@ -4,10 +4,8 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Because we cannot test CSS programatically with SimpleTest, the CSS below can
- * be useful for debugging with SimpleTest's verbose mode. Note that since the
- * DOM cannot be manipulated via CSS, JavaScript loading needs to be functional
- * for this to have any visible effect.
+ * Color the 'libraries-test' div orange. See example_installed.txt for more
+ * information.
  */
 
 div#libraries-test {
Index: tests/example/example_installed_variant_1.js
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/example/example_installed_variant_1.js,v
retrieving revision 1.1
diff -u -p -r1.1 example_installed_variant_1.js
--- tests/example/example_installed_variant_1.js	23 Jul 2010 12:57:01 -0000	1.1
+++ tests/example/example_installed_variant_1.js	28 Aug 2010 15:56:56 -0000
@@ -4,8 +4,8 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Because we cannot test JavaScript programatically with SimpleTest, the
- * JavaScript below can be useful for debugging with SimpleTest's verbose mode.
+ * Insert a 'libraries-test' div and some text below the page title. See
+ * example_installed.txt for more information.
  */
 
 (function ($) {
@@ -16,4 +16,4 @@ Drupal.behaviors.librariesTest = {
   }
 };
 
-})(jQuery); 
+})(jQuery);
Index: tests/example/example_installed_variant_2.css
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/example/example_installed_variant_2.css,v
retrieving revision 1.1
diff -u -p -r1.1 example_installed_variant_2.css
--- tests/example/example_installed_variant_2.css	23 Jul 2010 12:57:01 -0000	1.1
+++ tests/example/example_installed_variant_2.css	28 Aug 2010 15:56:56 -0000
@@ -4,10 +4,8 @@
  * @file
  * Test CSS file for Libraries loading.
  *
- * Because we cannot test CSS programatically with SimpleTest, the CSS below can
- * be useful for debugging with SimpleTest's verbose mode. Note that since the
- * DOM cannot be manipulated via CSS, JavaScript loading needs to be functional
- * for this to have any visible effect.
+ * Color the 'libraries-test' div blue. See example_installed.txt for more
+ * information.
  */
 
 div#libraries-test {
Index: tests/example/example_installed_variant_2.js
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/libraries/tests/example/example_installed_variant_2.js,v
retrieving revision 1.1
diff -u -p -r1.1 example_installed_variant_2.js
--- tests/example/example_installed_variant_2.js	23 Jul 2010 12:57:01 -0000	1.1
+++ tests/example/example_installed_variant_2.js	28 Aug 2010 15:56:56 -0000
@@ -4,8 +4,8 @@
  * @file
  * Test JavaScript file for Libraries loading.
  *
- * Because we cannot test JavaScript programatically with SimpleTest, the
- * JavaScript below can be useful for debugging with SimpleTest's verbose mode.
+ * Insert a 'libraries-test' div and some text below the page title. See
+ * example_installed.txt for more information.
  */
 
 (function ($) {
@@ -16,4 +16,4 @@ Drupal.behaviors.librariesTest = {
   }
 };
 
-})(jQuery); 
+})(jQuery);