No documentation on how to define a library

Great start, and thanks for reviving this issue!

I have a few suggestions:

1. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   * Info files are formatted as YAML. If the 'version' key is set to 'VERSION'
   +   * in any info file, then the value will be substituted with the current
   +   * version of Drupal core. Each library is listed as an entry detailing the
   +   * CSS and JS assets.
   +   *
   

   I would put this information about the version key in the docs below that tell about 'js', 'css', and etc.

2. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   * Info files are formatted as YAML. If the 'version' key is set to 'VERSION'
   +   * in any info file, then the value will be substituted with the current
   +   * version of Drupal core. Each library is listed as an entry detailing the
   +   * CSS and JS assets.
   +   *
   

   Actually, maybe this whole paragraph can be omitted? We could just say something like:

   Library information is parsed from *.libraries.yml files; see foo.library.yml for an example. Each entry starts with a machine name, and the information below has the following elements:

   and then list the js, css, etc. as well as the note about VERSION.

3. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   * @code
   +   * drupal.editor:
   +   *   version: VERSION
   +   *   js:
   

   I don't think we really need to put in a full example of a libraries.yml file in here. I would instead suggest saying something like "See foo.libraries.yml for an example" (replace 'foo' with the name of an actual library file that exists in Core).

4. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   * Information stored in all .libraries.yml entries:
   

   This is the line I'd suggest combining with that previous paragraph.

5. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   *   forward slash, in which case it is relative to the Drupal root. If the
   +   *   file path starts with 2 forward slashes, it will be treated as an
   

   Maybe instead of saying "forward slash" just put in '/' and '//'? More concise?

6. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   * - 'js': A list of Javascript files to include. Each file is the key of an
   

   Actually, we don't normally want to put '' on list item keys. See https://www.drupal.org/node/1354#lists

7. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   *   object definition, which allows modules to set attributes for the
   +   *   particular file, like weight or HTML attributes. The path of the file is
   +   *   relative to the module or theme directory, unless it starts with a
   +   *   forward slash, in which case it is relative to the Drupal root. If the
   +   *   file path starts with 2 forward slashes, it will be treated as an
   +   *   external resource. Required if no 'css' key is present.
   

   This probably needs more details. I cannot figure out what it means.

8. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   *   external resource. Required if no 'css' key is present.
   

   Maybe this would be clearer if it said "Every library needs to have at least one js or css entry"?

9. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
   +   *   Just like with Javascript files, each CSS file is the key of an object
   +   *   which can define specific attributes. The available categories are:
   +   *   - 'base'
   

   Hm, again not really sure what this means? What are "categories"?

10. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
    @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
    +   * See editor.libraries.yml for an example of a module .libraries.yml file.
    

    Ah, I see you have an example listed; just move this up into the main paragraph. :)

11. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
    @@ -208,6 +208,75 @@ public function buildByExtension($extension) {
    +   * See @link https://www.drupal.org/node/2274843#define-library Defining a library @endlink
    

    We can leave out the @link here. Just say "See https://whatever for more information".

Great! I agree that the short examples you put in this time are good and necessary, and I think it's much better this way than including a whole example with documentation that is separate.

A few things to address:

1. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,57 @@ public function buildByExtension($extension) {
   +   * - js: A list of Javascript files to include. Each file is keyed by the file
   

   Nitpick: should be JavaScript not Javascript throughout this patch

2. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,57 @@ public function buildByExtension($extension) {
   +   *   which can define specific attributes. The format of the file path is the
   

   Nitpick: which -> that

3. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,57 @@ public function buildByExtension($extension) {
   +   * - version: If the version key is set to "VERSION", then the value will
   +   *   be substituted with the current version of Drupal core.
   

   We should probably start by saying "The library version." before launching into saying about the "VERSION" special value. :) Also I think this would be clearer if it said:

   version: The library version. The string "VERSION" can be used to mean the current Drupal core version.

4. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,57 @@ public function buildByExtension($extension) {
   +   * @todo Document the following keys and their usage:
   

   We need to take care of this before the patch is finalized. Alternatively, if we think these are not used much, we could just put in another - list item saying something like:

   - Additional information can also be specified, such as the weight. See ... for more information.

Looking good! I'm sitting next to you, so these comments are brief, so others can see the review:

1. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,61 @@ public function buildByExtension($extension) {
   +   *   The path of the file is relative to the module or theme directory, unless
   +   *   it starts with a /, in which case it is relative to the Drupal root. If
   +   *   the file path starts with //, it will be treated as an external resource.
   +   * - css: A list of categories for which the library provides CSS files. The
   +   *   available categories are:
   

   Need to talk about stream wrappers and http:// stuff here?

2. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,61 @@ public function buildByExtension($extension) {
   +   *   set this to true. Defaults to false.
   

   Should use TRUE and FALSE in docs, not true/false.

3. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,61 @@ public function buildByExtension($extension) {
   +   * - remote: If the library is a third-party script, this provides the
   +   *   repository URL.
   +   * - license: If the remote property is set, the license information is
   

   Maybe say something like "for reference"? I think this is just for documentation and/or human readers so they can visit the project page, right?

4. +++ b/core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
   @@ -208,6 +208,61 @@ public function buildByExtension($extension) {
   +   *   - gpl-compatible: A boolean for whether this library is GPL compatible.
   

   boolean => Boolean

Thanks! I think this is ready to go now.

Is the page on drupal.org wrong? The point of this issue was to make sure we have docs on api.drupal.org about libraries. I don't think there was a problem with the d.o docs.