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.
Comment | File | Size | Author |
---|---|---|---|
#6 | interdiff-2933773-2-6.txt | 2.28 KB | masipila |
#6 | 2933773-6.patch | 1.95 KB | masipila |
#2 | 2933773-2.patch | 2.5 KB | masipila |
Comments
Comment #2
masipila CreditAttribution: masipila as a volunteer commentedInitial patch attached. When writing the patch, I found out a couple of other nits that I fixed at the same time. Issue summary updated.
Comment #3
masipila CreditAttribution: masipila as a volunteer commentedIS formatting.
Comment #4
quietone CreditAttribution: quietone as a volunteer commentedIt does look like the handbook page doesn't really add a lot of value and it makes sense to enhance the api doc.
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.
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?
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.
Comment #5
masipila CreditAttribution: masipila as a volunteer commentedComment #6
masipila CreditAttribution: masipila as a volunteer commentedI removed the additional examples from the configuration key descriptions but clarified the typical combination of skip_on_empty and migration_lookup in the end.
Comment #7
phenaproximaI think this looks good. RTBC once it pleases Drupal Ci.
Comment #8
Gábor HojtsyLooks like a definite improvement, thanks all!