[meta] Add process plugin documentation to the codebase

+1

Me too!

The question is, should we do this instead of #2682461: Add links to documentation in all migrate process plugins or as a follow-up to it?

Okay, let's postpone this on that then.

+++ b/core/modules/migrate/src/Plugin/migrate/process/Substr.php
@@ -9,7 +9,39 @@
+ * @code
+ * process:
+ *   new_text_field:
+ *     plugin: substr
+ *     source: some_text_field
+ *       start: 2
+ *       length: 7
+ * @endcode
+ *
+ * If some_text_field was 'Marie Skłodowska Curie' then
+ * $destination['new_text_field'] would be 'Skłodowska'.
+ *
+ * The PHP equivalent of this is:
+ *
+ * @code
+ * $destination['new_text_field'] = substr($source['soume_text_field'], 6, 10)
+ * @endcode

Number don't add up!

+++ b/core/modules/migrate/src/Plugin/migrate/process/Substr.php
@@ -19,6 +51,8 @@ class Substr extends ProcessPluginBase {
   /**
    * {@inheritdoc}
+   *
+   * @throws \Drupal\migrate\MigrateException
    */

Doc standards states that a {@inheritdoc} docstring should not be accompanied by any other text. See https://www.drupal.org/node/2606724

The other issue has been committed, so we can work on this one again now. Thanks!

I put such things in the handbook because the edit process at the time at least was significantly faster than editing core documentation. I am not familiar enough either with the new core development cycles in semver times or the new documentation structure, did this change enough that we want to move from handbook into core?

If this is to replace the handbook pages then we should have a follow-up to delete those nodes and redirect the URL's to the pages that are hopefully auto generated from these new docs?

Let's add a TODO for #16. And rather than bikeshed on wording, I'm inclined to get er done and RTBC and improve docs with follow-up issues (as needed).

For the incomplete docs, if you don't think they are complete enough, let's open specific TODOs to improve each of them and get this committed, warts and all.

Well, started going through this, and it's simply too much to do all in one go, especially since there are some particular plugins (I'm looking at you, iterator, and your worst-case-scenario example) that will take some bikeshedding to get nice and clear. Let's split it out per-plugin, so the nasty ones don't delay finishing up the simpler ones, and the simpler ones can be novice tasks (both on the writing and reviewing side).

Actually, opening up child issues would itself be a novice task...

One more word on the handbook - I think that will still be useful for elaborating on different use cases and more advanced examples of plugin usage, while the code docs should stick to simple straight-forward examples.

Repurposed the "De-duplication is confusing" issue as the child for documentation the dedupe plugins.

What strikes me about this is what type of examples go where?

My feeling is that you can never have too many examples, in general -- it's not so much a question of which examples should go where, but how many examples can go where. The API docs should contain two examples at most -- maybe three for more complex process plugins -- and cover the most common use cases. The handbook pages, on the other hand, can have as many examples as we want to put there, covering any range of use cases, from the most basic to the most exotic. What do we think about this?

Just a very small whitespace nitpick; these have had lists indented one level too many so please double-check that the patches under review comply with this: https://www.drupal.org/node/1354#lists

Thanks!

There's only a single issue left here. So i'm going to close this down.

#2845485: Refactor and document the MenuLinkParent process plugin is the only outstanding process plugin docs issue left open.

No can do, #2845483: Rename Iterator process plugin and add documentation is also open.

Re-opening. I missed #2845483: Rename Iterator process plugin and add documentation. There are still two issues.

Someone double-check me, but I think we are down to only a single child issue: #2845485: Refactor and document the MenuLinkParent process plugin

If that is true, let's get some attention on it so we can close this thing down.

No feedback. Going to mark this meta fixed as there is only a single child issue open. Thank to all who helped with the docs.