Number lists are not supported in docs - use bullet lists

I do not think 4 instances is enough to warrant adding this feature to the API module or to the coding standards. Let's instead fix the code docs to use bullet lists, which are well supported.

We are not parsing JS files in the API module... and the existing numbered lists are in violation of our current coding standards. Making changes to the standards is a pain, too.

So I guess the question is whether the numbered lists are really needed or not. I doubt that they are. From recent issues where these have been fixed in a few places, they're usually easy to replace with bullet lists, and the bullet lists are actually more readable from what I've seen.

Agreed replacing the lists with bullets would be a good solution.

If other documentation comment parsers support numbered lists, we can treat this as a Feature request to get parity with them.

If we do, I doubt we'll support the syntax that is in Drupal Core now. Other parsers (markdown, etc.) use something like # or . as prefixes for numbered lists, not individual numbers on the items.

But I just don't see a strong reason to want to have them in Drupal docs right now.

Number lists in // comments are not a problem. These comments are not parsed/displayed. It's only in /** */ comments that we should not (currently) be using numbered lists.

It's also not a problem if the numbered items are in separate paragraphs, because (although it's probably not ideal) the numbered paragraphs will at least be rendered OK.

So the only problem is if someone creates a numbered list that is formatted like this:

/**
 * First line of documentation.
 *
 * Here are the steps:
 * 1. First step goes here.
 * 2. Second step goes here.
...

If we have a *lot* of these, then it may be worth going through the (currently totally broken and always fairly lengthy) process of updating the comment/code standards to define a way to make numbered lists. But this will *still* probably require patching the comments, because the standard we should adopt is more in line with what other docs parsers do, something like what we do with bullet lists but using # instead of - for the list items.

I really don't think it's worth it. I still think there are not many places, and they aren't less understandable as bullet lists.

So let's just fix the bad lists, which I think are only a few spots.

Thanks! Yeah, not a lot of stuff to fix... So this is a good start, but the lists do not quite conform to our lists in docs standards -- see https://www.drupal.org/node/1354#lists

Some specific items to address (representative of what needs fixing, but not listing all spots that need fixing) -- basically the indentation, punctuation, and capitalization needs to be adjusted throughout:

1. +++ b/core/includes/install.core.inc
   @@ -1160,14 +1160,14 @@ function install_select_profile(&$install_state) {
     * A profile will be selected in the following order of conditions:
     *
   - * 1. Only one profile is available.
   - * 2. A specific profile name is requested in installation parameters:
   + * - Only one profile is available.
   + * - A specific profile name is requested in installation parameters:
   

   There should not be a blank line between the explanation line ending in : and the start of the list.

2. +++ b/core/includes/install.core.inc
   @@ -1160,14 +1160,14 @@ function install_select_profile(&$install_state) {
   + * - A specific profile name is requested in installation parameters:
     *    - for interactive installations via request query parameters.
     *    - for non-interactive installations via install_drupal() settings.
   

   In the indented bullet list, just indent 2 spaces. Also the bullet items should start with capital letters.

3. +++ b/core/includes/install.core.inc
   @@ -1160,14 +1160,14 @@ function install_select_profile(&$install_state) {
   + * - A discovered profile that is a distribution.
     *    If multiple profiles are distributions, then the first discovered profile
     *    will be selected.
   - * 4. Only one visible profile is available.
   

   The second and third lines should be wrapped with the first one here, unless it's meant to be an indented bullet item, in which case it needs to start with - ... I think just wrap it.

4. +++ b/core/lib/Drupal/Core/Cache/CacheContexts.php
   @@ -204,8 +204,8 @@ protected function getService($context_id) {
       *   containing:
   -   *   1. the cache context ID
   -   *   2. the associated parameter (for a calculated cache context), or NULL if
   +   *   - the cache context ID
   +   *   - the associated parameter (for a calculated cache context), or NULL if
       *      there is no parameter.
   

   Bullet items should start with capital letters. Also the second line of a bullet item should be indented just 2 spaces (it's 3 here).

5. +++ b/core/lib/Drupal/Core/Menu/MenuLinkTreeElement.php
   @@ -17,10 +17,10 @@
   - *   1. all additional metadata from {menu_tree}, which contains "materialized"
   + *   - all additional metadata from {menu_tree}, which contains "materialized"
     *      metadata about a menu link tree, such as whether a link in the tree has
     *      visible children and the depth relative to the root;
   - *   2. plus all additional metadata that's adjusted for the current tree query,
   

   Same problem as in CacheContexts... check rest of patch for this?

6. +++ b/core/modules/filter/src/FilterProcessResult.php
   @@ -17,14 +17,14 @@
   + * - declare asset libraries to be loaded;
   + * - declare cache tags that the filtered text depends upon, so when either of
     *   those cache tags is invalidated, the filtered text should also be
   

   Bullet items should end in .

7. +++ b/core/modules/language/src/Tests/LanguageUILanguageNegotiationTest.php
   @@ -25,7 +25,7 @@
     * Tests UI language switching.
     *
   - * 1. URL (PATH) > DEFAULT
   + * - URL (PATH) > DEFAULT
     *    UI Language base on URL prefix, browser language preference has no
   

   Before any list, there should be an explanation line ending in :

Yes, I think those repeated lines in LanguageUILanguageNegotiationTest would be good to consolidate. Maybe you can just say something like:

blah blah blah for each of these, the following are tested:
- admin/config etc.

Nice work consolidating that documentation block already, by the way! It is already a LOT more readable than the original in the code, and I'm sure *much* more readable on the API site with this patch.

So everything else in this patch looks perfect. Let's just fix this one area and get it in. Thanks!

(you probably figured this out but when you upload an interdiff, make the extension .txt so it will not get test bot review)

Actually, URL is correct in text, not Url. It's an acronym. It's just that in method names we use CamelCaseEvenForAcronymsLikeUrlAndHtml.

Changing PATH, BROWSER, etc. to lower-case is good though!

And here:

+ * The paths that are used for each of these , are:

you don't want a space before the ,

Good catch in RendererPostRenderCacheTest.php -- I missed that one. Rest looks good!

Looks good now, thanks!

Docs are not frozen in beta. Committed 5ad5c13 and pushed to 8.0.x. Thanks!