Add documentation to EntityContentBase destination plugin

This one is also a bit tricky, but here's a start. I have added:

• available configuration key(s)
• a simple example
• a second example incorporating the translation config key

I couldn't identify destination properties the same as I did with #2862655: Add documentation to Config destination plugin and #2862751: Add documentation to PerComponentEntityDisplay destination plugin.

Great start, and good examples.

* "the destination is for translations" is hard to understand. It would be clearer as "the destination will be associated with the langcode provided by the source plugin."
* I would remove the "signature/value" key from the second example entirely; it's just confusing and doesn't provide anything the mail and name keys don't already.
* "This will add the results of the process..." would be clearer as "This will migrate mapped data ("nid" and "uid") into a "user" entity". This change can apply to both descriptive sentences.

I changed the example from a user migration to a node migration because we are demonstrating the overwrite_properties configuration key in the example and overwriting user account data is a bit too dangerous to be used as an example in my opinion.

The interdiff is included but does not make much sense as the example is changed.

Cheers,
Markus

My concern on using the user migration as an example is this:

• Let's say that users have been migrated to D8
• New users have been created to D8
• If the user migration is executed again, it is very likely that there will be ID conflicts and the migration will overwrite user account created in D8.
• The same thing of of course applies also to node migrations but it would not be as fatal as the user ID conflict.

I do agree, however, that the user migration needs to be documented but we already have a handbook page for that purpose and that handbook page includes the password hashes, see https://www.drupal.org/docs/8/api/migrate-api/migrate-destination-entity...

I'll propose the following for this API documentation:

• Let's have two examples: one for user migration and another for node migration
• Let's use the user migration as the first example without the optional overwrite_properties configuration and let's add a link to the handbook page for more details on the password handling.
• Let's use the node migration as the second example which is more complex and discusses the overwrite_properties configuration.

Patch will follow shortly.

Markus

Hmm.. Continuing to think out loud regarding the user migration example.

I don't think that the user migration example belongs here to EntityContentBase destination plugin. We have a separate subclass EntityUser for migrating user entitities and that destination plugin has the capabilities for the password MD5 hashes.

I created a follow-up to improve the API documentation of EntityUser, see #2933310: Add documentation to EntityUser destination plugin.

Cheers,
Markus

Changes since #6: Added a third field which will be preserved in an update. Improved phrasing.

I added the translation to the example directly so that the developer doesn't have to jump back and forth but can get a comprehensive example from here (also changed the example values to Finnish).

I also re-phrased the text so that we don't 'hard code' the destination version to Drupal 8.

Markus

Added a 'see also' reference to \Drupal\migrate\Plugin\migrate\destination\EntityRevision. See #2862748: Add documentation to EntityRevision destination plugin. These two patches should be preferably be committed at the same time.

Cheers,
Markus

EDIT: Fixed the correct issue number for EntityRevision.

1. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityContentBase.php
   @@ -17,7 +17,61 @@
   + * - overwrite_properties: (optional) A list of properties that will be
   + *   overwritten if an entity with the same ID already exists.
   

   Is this always overwritten, even if the update flag wasn't passed when running the migration?

   Update: I see this is mentioned later. But can we work it into the initial short description too?

2. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityContentBase.php
   @@ -17,7 +17,61 @@
   + *   plugin: empty
   

   Might try using the embedded source plugin instead of empty.

improved on the doc section.

#18 doesn't see to address any of the feedback points in #17.

Addressed the feedback from #17 (ignoring the patch in #18).

All my feedback is addressed. On to RTBC.

Let's use the embedded_data source plugin instead of d7_node (see #17) so that we are providing a working stand-alone example. In addition to this, the patch #15 gave an explicit example on how the fields are overwritten on update because the source data was visible in the example.

I can take this on Friday if this hasn't been worked before that.

Markus

Working on this now.

The attached patch uses #15 as the basis and changes the source plugin to EmbeddedDataSource as heddn suggested in #17 (and fixes the typo Jo spotted in his patch + adds the claficication from Jo's patch).

Cheers,
Markus

All feedback is addressed. On to RTBC.

Argh. The previous patch is missing the ids part of the embedded data source... fixing right now... sooorrry.

And now it should be done.

Oops. Missed that. Now I think we are good to go.

Looks good, thanks all!