Review and update the ajax @defgroup in ajax.inc

Thanks! This definitely needs to be done. Adding to the "api landing page" meta, since this is one of the landing topics.

I think I can take this one on. It's been partially updated for D8, but things have changed since it was first done so it needs more updates.

Here's a first pass at a patch.

As a note, in D7 there was a separate topic that listed the available Ajax commands. I figured we didn't really need 2 topics, so I added all the available command classes with @ingroup to this topic.

The text has (obviously) also been completely rewritten. I believe it to be accurate, and took examples from actual, presumably working code. Obviously needs a review; it should hopefully, at a minimum, be a lot better than the mostly D7 disorganized mess that was there!

1. +++ b/core/includes/ajax.inc
   @@ -8,221 +8,152 @@
   + * @sec sec_framework Using the Drupal Ajax framework in forms
   + * The primary way to use the Drupal Ajax framework is within forms that use the
   + * Drupal Form API (see the @link form_api Form API topic @endlink for more
   

   In the previous bit you changed it from using framework to API which is an improvement TBH. Should we also mention the other way: define route which returns an Ajax Response object? I see it is written below, not sure how it will be displayed at the end of the day.

2. +++ b/core/includes/ajax.inc
   @@ -8,221 +8,152 @@
   + * - path: The URL path to use for the request. If omitted, defaults to
   + *   'system/ajax', which invokes the default Drupal Ajax processing (this will
   + *   call the callback supplied in the 'callback' element). If you supply a
   + *   path, you must set up a routing entry to handle the request yourself and
   + *   return output described in @ref sub_callback below. See the
   + *   @link menu Routing topic @endlink for more information on routing.
   

   Do we support routes + route parameters here already? Just curios

3. +++ b/core/includes/ajax.inc
   @@ -8,221 +8,152 @@
   + * - wrapper: The HTML 'id' attribute of the area where the content returned by
   + *   the callback should be placed. Note that callbacks have a choice of
   + *   returning content or JavaScript commands; 'wrapper' is used for content
   + *   returns.
   

   OT: Did we considered to not use ajax IDs but classes/data attributes?

4. +++ b/core/includes/ajax.inc
   @@ -8,221 +8,152 @@
   + * - Add property '#autocomplete_route_name' to a text field in a form. The
   + *   route controller for this route must return an array of options for
   + *   autocomplete, as a \Symfony\Component\HttpFoundation\JsonResponse object.
   + *   See the @link menu Routing topic @endlink for more information about
   + *   routing.
   

   I am not sure whether it really makes sense to mention this here. The autocompletion framework is orthogonal to the ajax one.

Thanks for the review! I think I've addressed #1... a few notes on the other comments:

#2 - I do not see anything in core using routes instead of paths in #ajax, but I didn't look at everything. No idea really.

#3 - I also have no idea on that. I just wrote up what I saw being used, and/or borrowed documentation from other sources.

#4 - As far as I know, the only other place we document autocomplete is in the form API reference, which is outdated especially for Drupal 8, not to mention nearly impossible to patch. Autocompletes are Ajax, although I agree the framework for handling autocompletes in Drupal is not the same at all as the other Ajax stuff.... I'd prefer to keep it in the patch though, since it's pretty simple and it doesn't really need its own topic, I think?

New patch...

This needs more proofreading. Let me take another look at it...

OK, not much! But I noticed two typos while working on something else and referring to this patch.

Shoot. No longer applies.

Something in there changed, needed a reroll.

Missed one thing in the reroll

Ok cool, this sat here for a month without any issues so I'm going to go ahead and get this in.

Committed and pushed to 8.x. Thanks!