Issue #2236983 by quietone, DenEwout: Not at all clear how/when...

Issue #2236983 by quietone, DenEwout: Not at all clear how/when Database::addConnectionInfo should be called

core/lib/Drupal/Core/Database/Database.php

@@ -254,7 +254,9 @@ final public static function parseConnectionInfo(array $info) {
    * Under normal circumstances the preferred way to specify database
    * credentials is via settings.php. However, this method allows them to be
    * added at arbitrary times, such as during unit tests, when connecting to
-   * admin-defined third party databases, etc.
+   * admin-defined third party databases, etc. Use
+   * \Drupal\Core\Database\Database::setActiveConnection to select the
+   * connection to use.
    *
    * If the given key/target pair already exists, this method will be ignored.
    *
@@ -266,6 +268,8 @@ final public static function parseConnectionInfo(array $info) {
    *   The database connection information, as defined in settings.php. The
    *   structure of this array depends on the database driver it is connecting
    *   to.
+   *
+   * @see \Drupal\Core\Database\Database::setActiveConnection
    */
   final public static function addConnectionInfo($key, $target, array $info) {
     if (empty(self::$databaseInfo[$key][$target])) {