Document service tags, other than those related to service collectors

Nice!

Um. Pretty sure that this needs a lot more work, if the issue summary is correct. :) Also:

+ *     - method: string | default: 'access' | ?

needs to not be a ? :)

Jennifer is usually the best person for those kind of questions. Not usually around on the weekends, though.

So this issue was originally created as critical as a clone of #2264047: [meta] Document service definition tags which in turn was critical as part of #2238935: [meta] Complete missing documentation for special strings and metadata like annotation keys, routing parameters, tagged services, etc.. However, the API for service tags itself is already well-documented,Furthermore, you can discover what these services are for by looking at the services core provides (though having more central documentation on api.d.o will definitely make it easier to discover). I don't think we would block release on adding this documentation. Based on that, downgrading to major, if @jhodgdon agrees, because I do think the documentation on on api.d.o will be helpful.

updated the issue summary with all the locations I could find.

tagged all the locations with the patch, it's a little easier to work on now, I guess

added the "this tag is processed by" to all spots
and I think I didn't have the persist one saved before.

I don't think I was the one who decided any of these would be critical. ;} Fine with Major. Or even normal.

Anyway I took a quick look through the latest patch and it needs some work:

+ *   This tag is processed by
+ *   Drupal\Core\Cache\CacheContextsPass

Any time you use a class in docs it needs to start with \ and I think these can mostly all fit on one 80-character line as well?

Also please don't use gender pronouns:

+ *   A module developer has to tag his backend service with "backend_overridable":

Actually all of that documentation in the BackendCompilerPass looks like it is out of scope for this issue... if it is in scope it needs to all be rewritten and reformatted.

And for lists, like:

+ *   parameters:
+ *     - applies_to: string | The path requirements matching this check.
+ *     - method: string | default: 'access' | ?
+ *     - needs_incoming_request: bool | default: TRUE

Please read the list formatting guidelines:
https://www.drupal.org/node/1354#lists

Obviously the @todo parts need to be done too.

I found this in entity.api.php:

 *   - translatable: (optional) A boolean value specifying whether this bundle
 *     has translation support enabled. Defaults to FALSE.

So I'm going to use that as the template for the parameters.

I inserted the "\"s and moved those that would fit under the 80 char limit to one line.

"I didn't do it!!" I just moved that text under the service tag that was already in that class header. I moved it back to where it was, but I did change it to remove the gender pronoun.

I reworked the parameter list as best I could to conform to the standards you pointed to.

For all the stuff that's marked @todo, I think you really need someone other than me to do that writing. This is only my second week in Drupal, and while I'm loving what I've learned so far, and more than happy to help out with moving some of these tickets along, I'm probably not qualified to speak to the content of each of these.
It would probably only take the right person 2 minutes or less to write a blurb on each one.

Did 1 and 3.
For #2, I tidyed up that bit, but it's probably going to get rewritten alot. When you say "except for long class names", does that mean like the "This tag is processed by" lines, or should those still be broken up if they go over 80?

#15 is correct. And yes let's be nit-picky at all points. ;)

And thanks for working on these patches!

Speaking of nitpicks... Aside from the @todo notes, and the comments in #15, here are a few more things that can be fixed by someone without specialized Drupal knowledge:

a)

+++ b/core/lib/Drupal/Core/DependencyInjection/Compiler/RegisterAccessChecksPass.php
+ * @service_tag access_check
+ *   Services that check access to routes must be tagged access_check to be
+ *   registered to the access_manager service. There are three parameters:
+ *     - applies_to: (optional) A string specifying the path requirements
+ *       matching this check. Defaults to @todo.
+ *     - method: (optional) A string @todo that does something. Defaults to
+ *       'access'.
+ *     - needs_incoming_request: (optional) A boolean specifying @todo. Defaults
+ *       to TRUE.

List formatting - the indentation is incorrect. See https://www.drupal.org/node/1354#lists

b)

+++ b/core/lib/Drupal/Core/DependencyInjection/Compiler/RegisterKernelListenersPass.php
@@ -10,6 +10,12 @@
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 
+/**
+ * @service_tag event_subscriber
+ *   @todo fill this in
+ *   This tag is processed by \Drupal\Core\DependencyInjection\Compiler\RegisterKernelListenersPass.
+ */
+
 class RegisterKernelListenersPass implements CompilerPassInterface {

Wow. This class doesn't have a docs header. That is really bad. Can we at least just add one line of docs header for this class, and then put the @service_tag inside that docs header, rather than putting the @service_tag part separate from the class declaration?

c)

+++ b/core/lib/Drupal/Core/DependencyInjection/Compiler/RegisterStreamWrappersPass.php
@@ -14,6 +14,13 @@
 
 /**
  * Adds services tagged 'stream_wrapper' to the stream_wrapper_manager service.
+ *
+ * @service_tag stream_wrapper
+ *   To define a stream wrapper service, it should be tagged with
+ *   'stream_wrapper', either statically or dynamically. See
+ *   @link https://www.drupal.org/node/2393323 CR. @endlink
+ *   @todo update and revise
+ *   This tag is processed by \Drupal\Core\DependencyInjection\Compiler\RegisterStreamWrappersPass.
  */
 class RegisterStreamWrappersPass implements CompilerPassInterface {
 

I wouldn't use the word "should". This is actually a requirement. So say "Services that provide stream wrappers must be tagged with...". I think I'd also remove the "either statically or dynamically" part, what does that even mean?

Also when putting links to drupal.org or other web sites in documentation, it is not necessary to use @link. Just do something like:

* See https://www.drupal.org/whatever for more information.

Did #15 and #16 a, b, and c.
For c, I got it from that CR.

To define a stream wrapper that is always available, define it in yourmodule.services.yml like this:

and

If a stream wrapper should only be available dynamically, like private://, use a ServiceProvider:

I thought it was a pretty cool feature, so wanted to make some mention in the api docs.

Thanks for letting me work on this stuff. I enjoy it, I'm learning a lot, and hopefully I'll be a consumer of the api docs if I can get some consulting work with D8 after it's released.

Latest changes look good! Of course the patch still needs work for the @todo items.

There are still numerous @todo lines in the comments here.

Also, actually the parent issue has not been formally agreed to as the standard for how to do this and this should be postponed until it is.