[meta] Fill in plugin documentation

Can I help in this effort even though I don't have intimate knowledge of the code? Are there any simple tasks that need completed?

Upping to critical, because there's no way the system can be committed to core without decent documentation.

@cosmicdreams: thanks for the offer. I don't know yet, but will post ideas on how to proceed once I have them. Maybe neclimdul or someone else with intimate knowledge will post their ideas here as well.

Some of the work here might benefit from us first refining some terminology in #1560138: Refine terminology ?. Adding the link here so people can go "follow" that issue.

Moving things over here, as sun suggested:

I've been going backwards through the patch, superficially looking for coding style issues, to get a first idea of what this does. Thanks all! This looks pretty good.

Except some docblocks that are already marked with todos I've noticed these nitpicky things:

+++ b/core/lib/Drupal/Core/Cache/Cache.phpundefined
@@ -0,0 +1,25 @@
+/**
+ *
+ */

:)

+++ b/core/lib/Drupal/Core/Plugin/Discovery/HookDiscovery.phpundefined
@@ -0,0 +1,54 @@
+   * @todo

Should have a short description instead.

+++ b/core/modules/image/lib/Drupal/image/Effect.phpundefined
@@ -0,0 +1,31 @@
+ * Definition of Drupal\image\Effect.

This needs to have an @file, and should be seperated from the namespace statement with a newline.

+++ b/core/modules/image/lib/Drupal/image/Effect.phpundefined
@@ -0,0 +1,31 @@
+class Effect extends PluginType {

This class should have a docblock.

+++ b/core/modules/image/lib/Drupal/image/Effect.phpundefined
@@ -0,0 +1,31 @@
+    // Effects include translated strings.

Not sure what this means for us, here.

+++ b/core/modules/image/lib/Drupal/image/Effect.phpundefined
@@ -0,0 +1,31 @@
+  /**
+   *

:)

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTest.phpundefined
@@ -0,0 +1,98 @@
+<?php

This file needs a doc block ala "Defintion of x."

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTest.phpundefined
@@ -0,0 +1,98 @@
+class PluginTest extends PluginTestBase {

This class should have a docblock.

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTest.phpundefined
@@ -0,0 +1,98 @@
+  function testPluginDefintionFetching() {

This method should have a short docblock.

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTest.phpundefined
@@ -0,0 +1,98 @@
+  function testPluginInstanceFetching() {

This method should have a short docblock.

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTest.phpundefined
@@ -0,0 +1,98 @@
+  function testPluginDerivativeDefintionFetching() {

This method should have a short docblock.

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTest.phpundefined
@@ -0,0 +1,98 @@
+  function testPluginInstanceDerivativeFetching() {

This method should have a short docblock.

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTest.phpundefined
@@ -0,0 +1,98 @@
+  function testPluginEmptyDerivativeInstanceFetching() {

This method should have a docblock.

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTest.phpundefined
@@ -0,0 +1,98 @@
+  function testPluginGetDefinitions() {

This method should have a short description doc block, saying "Tests xyz.".

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTestBase.phpundefined
@@ -0,0 +1,25 @@
+<?php

This file needs a docblock, like "Defintion of ...".

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTestBase.phpundefined
@@ -0,0 +1,25 @@
+abstract class PluginTestBase extends UnitTestBase {

This class needs a docblock.

+++ b/core/modules/system/lib/Drupal/system/Tests/Plugin/PluginTestBase.phpundefined
@@ -0,0 +1,25 @@
+    // We're a unit test using classes... don't let the db registry blow up.

Is this still nescessary? If yes, maybe add @todo, so that we find this later.

+++ b/core/modules/system/tests/modules/plugin_test/lib/Drupal/plugin_test/Plugin/Derivative/DerivativeTest.phpundefined
@@ -0,0 +1,38 @@
+<?php

This file needs a docblock.

+++ b/core/modules/system/tests/modules/plugin_test/lib/Drupal/plugin_test/Plugin/Derivative/DerivativeTest.phpundefined
@@ -0,0 +1,38 @@
+class DerivativeTest implements DerivativeInterface {

This class should have a docblock. Btw. with the name DeriavativeTest this looks like a test case on the first glance.

+++ b/core/modules/system/tests/modules/plugin_test/lib/Drupal/plugin_test/Plugin/Derivative/DerivativeTest.phpundefined
@@ -0,0 +1,38 @@
+

Superflous empty line.

+++ b/core/modules/system/tests/modules/plugin_test/lib/Drupal/plugin_test/Plugin/TestPluginInstanceClass.phpundefined
@@ -0,0 +1,21 @@
+namespace Drupal\plugin_test\Plugin;
+use Drupal\Component\Plugin\PluginAbstract;

Put a newline between these?

+++ b/core/modules/system/tests/modules/plugin_test/lib/Drupal/plugin_test/Plugin/TestPluginInstanceClass.phpundefined
@@ -0,0 +1,21 @@
+class TestPluginInstanceClass extends PluginAbstract {

This class should have a docblock.

+++ b/core/modules/system/tests/modules/plugin_test/lib/Drupal/plugin_test/Plugin/Type/TestPluginType.phpundefined
@@ -0,0 +1,37 @@
+namespace Drupal\plugin_test\Plugin\Type;
+use Drupal\Component\Plugin\Discovery\DerivativeDiscoveryDecorator;
+
+use Drupal\Component\Plugin\PluginType;

We usually have a newline between namespace and use, but not between use statements.

+++ b/core/modules/system/tests/modules/plugin_test/lib/Drupal/plugin_test/Plugin/Type/TestPluginType.phpundefined
@@ -0,0 +1,37 @@
+class TestPluginType extends PluginType {

This class should have a docblock.

Yep, what's left to do from #7 is improving PHPDoc for the classes: Drupal\Core\Cache\Cache, Drupal\image\Effect, Drupal\system\Tests\Plugin\*, and Drupal\plugin_test\*.

This includes simple docs for Drupal\Core\Cache\Cache and Drupal\image\Effect. Leaving at "needs work" for test classes. Any volunteers?

Ahem. Let's try again.

#12 was committed. I think test docs are complete in #1638050: Provide real world values for derivative test. So, marking this issue fixed.

No more todos in plugins-next!!