From 8ac6a7c687556fc085362089836c134afb77aac3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20St=C3=B6ckler?= <tobiasstoeckler@googlemail.com>
Date: Mon, 4 Apr 2016 23:01:55 +0200
Subject: [PATCH] by tstoeckler: Start at providing high-level documentation
 for the new code architecture

Also fixes some unused use statements and a leftover .json which should be .yml
---
 libraries.api.php                             | 65 +++++++++++++++++++
 .../Registry/LibraryRegistry.php              |  2 -
 .../LibraryDefinitionsStream.php              |  2 +-
 3 files changed, 66 insertions(+), 3 deletions(-)

diff --git a/libraries.api.php b/libraries.api.php
index 637616f..6281a16 100644
--- a/libraries.api.php
+++ b/libraries.api.php
@@ -5,6 +5,71 @@
  * Documents API functions for Libraries module.
  */
 
+/**
+ * @defgroup libraries External libraries
+ * @{
+ * External libraries are not shipped as part of contributed modules for
+ * licensing and maintenance reasons. The Libraries API module aims to solve the
+ * problem of integrating with and loading external libraries as part of the
+ * Drupal request-response process in a generic way.
+ *
+ * @section sec_definitions Library definitions
+ * In order to do be useful to other modules Libraries API needs a list of
+ * known libraries and metadata about each of the libraries. Because multiple
+ * modules or themes may integrate with the same external library a key
+ * objective of Libraries API is to keep this information separate from any one
+ * module or theme.
+ *
+ * @subsection sub_definitions_machine_name
+ * A central part of a library's metadata is the library's machine name or ID.
+ * For maximum interoperability it must consist of only lowercase ASCII letters,
+ * numbers, and underscores. As the machine name is the single identifier of a
+ * library and is independent of any given module or theme name it must be
+ * unique among all libraries known to Libraries API.
+ *
+ * @subsection sub_definitions_history Historical background
+ * In Drupal 7 library information could already be provided by
+ * module-independent info files, but this was not widely used, because there
+ * was no way to distribute these info files properly. The information was
+ * predominantly provided by a hook that modules could implement, which caused
+ * race conditions between modules providing information for the same library.
+ * Thus, in Drupal 8 there is no longer a hook making it necessary to properly
+ * solve the problem of centrally maintaining and distributing library info
+ * files. This has yet to be done.
+ *
+ * @subsection sub_definitions_stream_wrapper
+ * In anticipation of a central repository of library information that will
+ * distribute library definitions as separate files Libraries API provides a
+ * 'library-definitions' stream wrapper. Due to that a library's definition can
+ * be accessed given only it's machine name, for example at
+ * 'library-definitions://example.yml' for a library with the machine name
+ * 'example'. YAML is chosen as the file format because it is used in many parts
+ * of Drupal 8 already. Using a stream wrapper has the benefit of being able to
+ * swap out the specific storage implementation without any other part of the
+ * code needing to change. For example, the specific directory which holds the
+ * library definitions on disk can be changed, multiple directories can be
+ * layered as though they were one, or the library definitions can even be
+ * read from a remote location without any part of the code other than the
+ * stream wrapper implementation itself needing to change.
+ *
+ * By default the library definitions stream wrapper reads from a single
+ * directory that is configurable and points to the 'library-definitions'
+ * directory within the public files directory by default. This makes library
+ * definitions writable by the webserver by default, which is in anticipation of
+ * a user interface that fetches definitions from a remote repository and stores
+ * them locally. For improved security the library definitions can be managed
+ * manually (or put under version control) and placed in a directory that is not
+ * writable by the webserver. The idea of using a stream wrapper for this as
+ * well as the default location is taken from the 'translations' stream wrapper
+ * provided by the Interface Translation module.
+ *
+ * @see \Drupal\libraries\ExternalLibrary\Registry\LibraryRegistryInterface
+ * @see \Drupal\libraries\ExternalLibrary\Registry\LibraryRegistry
+ * @see \Drupal\libraries\StreamWrapper\LibraryDefinitionsStream
+ *
+ * @}
+ */
+
 /**
  * Return information about external libraries.
  *
diff --git a/src/ExternalLibrary/Registry/LibraryRegistry.php b/src/ExternalLibrary/Registry/LibraryRegistry.php
index 0e59eac..5cb7dd2 100644
--- a/src/ExternalLibrary/Registry/LibraryRegistry.php
+++ b/src/ExternalLibrary/Registry/LibraryRegistry.php
@@ -12,8 +12,6 @@ use Drupal\Component\Serialization\SerializationInterface;
 use Drupal\libraries\ExternalLibrary\Exception\LibraryDefinitionNotFoundException;
 use Drupal\libraries\ExternalLibrary\Exception\LibraryTypeNotFoundException;
 use Drupal\libraries\ExternalLibrary\LibraryType\LibraryCreationListenerInterface;
-use Drupal\libraries\ExternalLibrary\LibraryTypeManagerInterface;
-use Drupal\libraries\ExternalLibrary\Local\LocalLibraryInterface;
 
 /**
  * Provides an implementation of a registry of external libraries.
diff --git a/src/StreamWrapper/LibraryDefinitionsStream.php b/src/StreamWrapper/LibraryDefinitionsStream.php
index da787c8..6748660 100644
--- a/src/StreamWrapper/LibraryDefinitionsStream.php
+++ b/src/StreamWrapper/LibraryDefinitionsStream.php
@@ -13,7 +13,7 @@ use Drupal\Core\StreamWrapper\LocalStream;
  * Provides a stream wrapper for library definitions.
  *
  * Can be used with the 'library-definitions' scheme, for example
- * 'library-definitions://example.json'.
+ * 'library-definitions://example.yml'.
  *
  * @see \Drupal\locale\StreamWrapper\TranslationsStream
  */
-- 
GitLab