Fix drush_commandfile_list() documentation

While investigating the various options for installing server-wide drush commands, I found some inconsistencies in the docs.

README.txt (commands section)

  - In a .drush folder in your HOME folder. Note, that you have
    to make the .drush folder yourself.
  - Along with one of your existing modules. If your command is
    related to an existing module, this is the preferred option.
  - In a folder specified with the include option (see above).
  - In /path/to/drush/commands (not a Smart Thing, but it would work).

drush_commandfile_list() documentation says:

 * - The ".drush" folder in the users HOME folder.
 * - The "/path/to/drush/includes" folder.
 * - Folders listed in the 'include' option (see example.drushrc.php).
 * - Active modules in the current Drupal installation (if any).

_drush_find_commandfiles() holds the truth:

      // Core commands shipping with drush
      $searchpath[] = realpath(dirname(__FILE__) . '/../commands/');

This reveals that the second line of documentation of drush_commandfile_list() is wrong.

      // User commands, specified by 'include' option
      if ($include = drush_get_option(array('i', 'include'), FALSE)) {

okay

      // System commands, residing in $SHARE_PREFIX/share/drush/commands
      $share_path = drush_get_context('SHARE_PREFIX', '/usr') . '/share/drush/commands';

Interesting, that's exactly what I was looking for! We need to put that in the docs!

      // User commands, residing in ~/.drush
      if (!is_null(drush_server_home())) {
        $searchpath[] = drush_server_home() . '/.drush';

okay

    case DRUSH_BOOTSTRAP_DRUPAL_SITE:
      $searchpath[] = conf_path() . '/modules';
      // Too early for variable_get('install_profile', 'default'); Just use default.
      $searchpath[] = "profiles/default/modules";
      // Add all module paths, even disabled modules. Prefer speed over accuracy.
      $searchpath[] = 'sites/all/modules';
      break;

We end up loading commands of modules which are not enabled (making the fourth item in the docs inaccurate). Actually, do we want to load the commands of disabled modules? What if you have the same function being defined multiple times? Also, many module commands are useless if the module is not enabled (e.g. features, etc.). Maybe we could drop the modules which are not enabled: right now $load_command = TRUE by default, that means if a module specifically does not want to be loaded by drush when disabled, it has to say so via hook_drush_load(), or am I missing some use case here?

    case DRUSH_BOOTSTRAP_DRUPAL_FULL:
      // Add enabled module paths. Since we are bootstrapped,
      // we can use the Drupal API.
      foreach (module_list() as $module) {
        $filename = drupal_get_filename('module', $module);
        $searchpath[] = dirname($filename);
      }

That does not change the fact that we'll also be loading disabled module commands which were added to $searchpath[] just before...

So this would be the suggested documentation for drush_commandfile_list():

/**
 * Collect a list of all available drush command files.
 *
 * Scans the following paths for drush command files:
 *
 * - The "/path/to/drush/commands" folder.
 * - Folders listed in the 'include' option (see example.drushrc.php).
 * - The system-wide commands folder $SHARE_PREFIX/share/drush/commands (e.g. /usr/share/drush/commands)
 * - The ".drush" folder in the user's HOME folder.
 * - All modules in the current Drupal installation.

I'm happy to roll a patch for drush_commandfile_list() including relevant changes for COMMANDS section of README.txt, but first I'd like some feedback on the question re disabled modules commands.