API refinements

Problem

There are 3 things that bother me with our current API.

1. libraries_detect_library being called by reference on the libraries array.
This forces you to do:

$library = libraries_info('foo');
libraries_detect_library($library);

instead of simply:

$library = libraries_detect_library(libraries_info('foo'));

Note that you can currently do:

$library = libraries_info('foo');
if (libraries_detect_library($library) && $library['installed']) {

which would then become:

if ($library = libraries_detect_library(libraries_info('foo')) && $library['installed']) {

2. libraries_detect_library() has the _library suffix, while libraries_info() and libraries_load do not.

3. libraries_detect_library() gets the entire the library array passed, while libraries_info() and libraries_load() simply take the name.

Background

The weirdness of libraries_detect_library was introduced because it was basically a helper of libraries_detect().

Proposal

1. Rip out the current libraries_detect()
This function is practically completely useless at least for implementing modules. No module would ever want to detect all libraries. It might make sense to detect all libraries for instance when visiting the libraries overview UI page (once there is such a thing), but that is theoretical at this point, and it's probably (though arguably) even more readable to simply loop over all libraries in a foreach.
2. Rename libraries_detect_library() to libraries_detect() and make it take the library's name as an argument.
It would then call libraries_info() on its own.
Modules could then do:

if ($library = libraries_detect('foo') && $library['installed']) {

Then we would have the following beautiful consistency:

// Just get some info about the library in general.
$library = libraries_info('foo');
// See whether the library is available, etc.
$library = libraries_detect('foo');
// Load it!
$library = libraries_load('foo');

The only inconsistency would be the following:

// This is valid code.
$libraries = libraries_info();
// This results in PHP erros.
$libraries = libraries_detect(); $libraries = libraries_load();

Though it would be about 5 LOC to either of the latter functions to support that behaviour.

Thoughts?