Security: LoggerChannelInterface doxygen needs a little love

+++ b/core/lib/Drupal/Core/Logger/LoggerChannelInterface.php
@@ -13,6 +13,11 @@
+ * This interface is the central Drupal logger facility. It allows using
+ * several \Psr\Log\LoggerInterface loggers, the default implementation picks
+ * up services tagged with the logger tag. Also, request specific information
+ * is provided so the log entries can provide more context.
  */

If this is the central place for loggers I think we should document how to use loggers. a) Inject one of the loggers from the core.services.yml file and b) not typehint against LoggerChannelInterface but rather LoggerInterface. Especially the later one seems not obvious reading the first sentence.

+++ b/core/lib/Drupal/Core/Logger/LoggerChannelInterface.php
@@ -13,6 +13,19 @@
+ * @see \Drupal\Core\Logger\\LoggerChannelFactoryInterface

Double "\\" :)

Wrote more docs. Also, in D7 we had function watchdog($type, $message, $variables = array(), $severity = WATCHDOG_NOTICE, $link = NULL) { in D8 it is possible to set $context['link'] instead but there's nowhere to document this because the LoggerInterface is in vendor.

Well, let's assume people read that interface you are patching. Then nothing blocks you from providing the same interface method again in our subinterface.
In general try to not be so pessimistic, this time we can actually make sense out of the documentation. The docs in D7 has been also just wrong.
You did not passed in a link, but rather a path / URL.

+++ b/core/lib/Drupal/Core/Logger/LoggerChannelInterface.php
@@ -13,6 +13,27 @@
+ * SECURITY NOTE: a 'link' can be set in the context array which will be
+ * printed as-is by the dblog module under an "operations" header. Usually
+ * this is a "view", "edit" or similar relevant link. Make sure to use proper,
+ * secure link generation facilities.

I'm confused because many of the callers in core specify a path there.

Oh you are absolutely right and I was blind from reading d6 code.

Um....

So I agree the interface docs need some love, but... After reading through these docs I was left with a lot of confusion. Can they get a bit more work please?

1. +++ b/core/lib/Drupal/Core/Logger/LoggerChannelInterface.php
   @@ -13,6 +13,27 @@
   + * This interface is the central Drupal logger facility. Despite this,
   + * \Psr\Log\LoggerInterface should be used for typehinting, not this interface.
   

   Why should this be done? I have no idea... why would we define this interface and then say not to use it?

2. +++ b/core/lib/Drupal/Core/Logger/LoggerChannelInterface.php
   @@ -13,6 +13,27 @@
   + * To add a new logger to the system, implement \Psr\Log\LoggerInterface and
   + * add a service for that class to a services.yml file tagged with the 'logger'
   + * tag. The default implementation of this interface will call every such
   + * logger service with some useful context (request_uri, referer, ip, user,
   + * uid).
   + *
   

   When I read this paragraph, I was confused in the 3rd line by "this interface"... is it referring to LoggerInterface or LoggerChannelInterface? The "this" is ambiguous because there are two interfaces (the one being documented and the one talked about in the paragraph). And I still don't know why we have our own interface here if we're just supposed to implement the PSR interface? Makes no sense to me.

   Actually I have no idea what this paragraph means. I'm sure it makes sense if you already know the information, but I don't and it doesn't... ???

3. +++ b/core/lib/Drupal/Core/Logger/LoggerChannelInterface.php
   @@ -13,6 +13,27 @@
   + * SECURITY NOTE: a 'link' can be set in the context array which will be
   

   What context array? Maybe this is related to one of the methods? If so it should say that and/or be documented on that method?

Why should this be done? I have no idea... why would we define this interface and then say not to use it?

That interface is about injecting some things into the logger. This is something the caller of a logger should not care about at all.
On top of that its also better to write code in the smallest interface as possible, as your code gets more compatible with PSR-3

OK, how about making that comment say something like:

This interface defines the full behavior of the central Drupal logger facility. However, when writing code that does logging, use the generic \Psr\Log\LoggerInterface for typehinting instead (you shouldn't need the methods here).

Looks good to me now, thanks!

LoggerChannelInterface's love has been received. Committed 3838074 and pushed to 8.0.x. Thanks!

I think that D7 should have a new issue since this interface does not exist there.

Fair enough. D7 follow-up:
#2540830: Sanitize watchdog() link in dblog_event()