Problem/Motivation

Process plugin documentation is being moved from the Handbook to the API documentation of the process plugin class.

The handbook page for process plugin contains more information than the API documentation of the plugin.

Before we delete the handbook page and redirect it to the API page, we need to either enhance the API doc or decide that it is OK to discard the additional information currently found in the handbook.

The difference is this:
--clips--
The handbook page gives an example use case for both plugin 'methods'.

For 'row' method:

  • API doc: "Skips the entire row when an empty value is encountered."
  • Handbook in addition to this: "This is useful when migrating parent values. When the parent source value is 0 or empty, which represents the root element, there is no need to set a destination value. In the other case a parent exists and needs a migration lookup."

For 'process' method:
API doc: "Prevents further processing of the input property when the value is empty."
Handbook in addition to this: "This is useful when combined with a migration process plugin to check if a related item was previously migrated."

(The handbook page also has more examples than the API page but the additional examples do not add much value as they only repeat what has been demonstrated already.)

When writing a patch for this, a couple of other issues were identified that should be fixed a the same time:

  • The example was using the 'migration' process plugin. This process plugin has been renamed to 'migration_lookup'.
  • API documentation standards: No newline between example code and the descriptive paragraph.
  • Needs minor improvements to phrasing.

Proposed resolution

Copy these pieces of 'this is useful' instructions to the API documentation.

Remaining tasks

Do it.

User interface changes

N/A.

API changes

N/A.

Data model changes

N/A.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

masipila created an issue. See original summary.

masipila’s picture

Issue summary: View changes
Status: Active » Needs review
FileSize
2.5 KB

Initial patch attached. When writing the patch, I found out a couple of other nits that I fixed at the same time. Issue summary updated.

masipila’s picture

Issue summary: View changes

IS formatting.

quietone’s picture

Status: Needs review » Needs work

It does look like the handbook page doesn't really add a lot of value and it makes sense to enhance the api doc.

  1. +++ b/core/modules/migrate/src/Plugin/migrate/process/SkipOnEmpty.php
    @@ -18,12 +18,18 @@
    + *   - row: Skips the entire row when an empty value is encountered. This is
    + *     useful when combined with a migration_lookup process plugin to check if a
    + *     related item was previously migrated.
    

    This is adding back information that was removed in the original documentation patch. See comment #27 in #2845488: Add documentation to SkipOnEmpty process plugin. To me, it doesn't seem needed here.

  2. +++ b/core/modules/migrate/src/Plugin/migrate/process/SkipOnEmpty.php
    @@ -18,12 +18,18 @@
    + *     is empty. This is useful when migrating parent values. An empty or 0 ...
    

    I think this, like the previous comment about the row property, should not be in the definition of the keys. Can this be moved to an example?

  3. Or maybe move these two items about the usefulness of the plugin to the paragraph before the key definitions, in the description of the plugin? Not sure.

masipila’s picture

Assigned: Unassigned » masipila
masipila’s picture

Assigned: masipila » Unassigned
Status: Needs work » Needs review
Issue tags: +Migrate January 2018 Sprint
FileSize
1.95 KB
2.28 KB

I removed the additional examples from the configuration key descriptions but clarified the typical combination of skip_on_empty and migration_lookup in the end.

phenaproxima’s picture

Status: Needs review » Reviewed & tested by the community

I think this looks good. RTBC once it pleases Drupal Ci.

Gábor Hojtsy’s picture

Status: Reviewed & tested by the community » Fixed

Looks like a definite improvement, thanks all!

  • Gábor Hojtsy committed 36ea4d3 on 8.5.x
    Issue #2933773 by masipila, quietone: Merge handbook documentation to...

  • Gábor Hojtsy committed a4c93ae on 8.6.x
    Issue #2933773 by masipila, quietone: Merge handbook documentation to...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.