Add documentation to FileCopy process plugin

Self-assigning for review.

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,31 @@
   + * The file_copy process plugin ...
   

   "The file_copy process plugin copies a file from one location to another. Optionally, the file can be moved, reused, or set to be automatically renamed if a duplicate exists."

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,31 @@
   + *   - source: The source path or URI.
   + *   - destination: The destination path or URI.
   

   Add example paths and URIs, including both relative and absolute examples.

3. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,31 @@
   + *   - move: (optional) If set the move the file otherwise copy the file.
   

   Boolean - set to FALSE by default.

4. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,31 @@
   + *   - rename: (optional) If set rename the file.
   

   Boolean: set to FALSE by default.

5. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,31 @@
   + *
   

   - reuse: (optional) Boolean, if TRUE, file can be reused. FALSE by default.

6. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,31 @@
   + *   new_text_field:
   + *     plugin: concat
   + *     source:
   + *       - foo
   + *       - bar
   + *     delimiter: /
   

   path_to_file:
   plugin: file_copy
   source: /path/to/file.png
   destination: /new/path/to/file.png

Changes in response to code review.

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -16,26 +16,31 @@
     * The source value is an array of two values
   

   This should end with a colon.

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -16,26 +16,31 @@
   + *   - source: The source path or URI, e.g. /path/to/foo.txt or
   + *     public://bar.txt.
   + *   - destination: The destination path or URI, e.g. /path/to/bar.txt or
   + *     public://foo.txt.
   

   These should align with the left of the comment, according to @xjm.

3. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -16,26 +16,31 @@
   + *   - move: (optional) Boolean, if TRUE, move the file otherwise copy the file.
   + *     Defaults to FALSE.
   

   Need to align this left. Also, should be a comma after "move the file".

4. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -16,26 +16,31 @@
   + *   - rename: (optional) Boolean, if TRUE, rename the file. Defaults to FALSE.
   

   Needs to align left. And should we maybe explain what renaming does in terms of actual behavior? As in, how is the file renamed?

5. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -16,26 +16,31 @@
   + *   - reuse: (optional) Boolean, if TRUE, file can be reused. Defaults to
   + *     FALSE.
   

   Align left, and explain what reusing means.

Changes in response to code review.

I'm cuckoo for great patches like this. Love it. Full steam ahead!

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,37 @@
   + * - source: The source path or URI, e.g. /path/to/foo.txt or
   + *   public://bar.txt.
   + * - destination: The destination path or URI, e.g. /path/to/bar.txt or
   + *   public://foo.txt.
   

   Can we put single quotes around example string values?

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -86,7 +116,22 @@ public static function create(ContainerInterface $container, array $configuratio
   +   * Performs the associated process.
   

   I have no idea what this means. :) Can we explain a little more?

3. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -86,7 +116,22 @@ public static function create(ContainerInterface $container, array $configuratio
   +   *   The sub string of $value.
   

   "Substring" should probably be one word, (since we are not talking about a vehicle that goes underwater or a sandwich). Also not sure what substring is meant by this? It's not explained in the documentation for this method.

Thanks everyone!

Changes in response to @xjm's code review in #11.

I'm sorry I missed these things last time. I think I was only looking at the interdiff...anyway, this time I have looked at the entire patch. Thanks, @Jo Fitzgerald, for addressing @xjm's comments -- just these things and then I think we're good to go:

+++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
@@ -116,7 +116,7 @@ public static function create(ContainerInterface $container, array $configuratio
-   * Performs the associated process.
+   * Copies a file between the source and destination given by $value.
    *
    * @param string $value
    *   The input string.
@@ -129,7 +129,7 @@ public static function create(ContainerInterface $container, array $configuratio

@@ -129,7 +129,7 @@ public static function create(ContainerInterface $container, array $configuratio
    *   with the $row above.
    *
    * @return string
-   *   The sub string of $value.
+   *   The final destination of the copied file.

This should all just be {@inheritdoc}. Process plugins' transform() method is defined on an interface, and interface method implementations should almost always inherit their documentation. I'm sorry I didn't catch this last time!

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,37 @@
   + * Copies or moves a local file from one place into another.
   + *
   + * The file_copy process plugin copies a file from one location to another.
   

   These sentences are redundant. Let's remove the second one.

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -14,7 +14,37 @@
   + * Optionally, the file can be moved, reused, or set to be automatically renamed
   

   Let us be rid of the "optionally".

Nice quick changes in response to @phenaproxima - we're nearly over the line with this one!

Looks fantastic.

Committed and pushed f57baee to 8.4.x and fb8ff16 to 8.3.x. Thanks!

I've opened a followup for this ticket as the added documentation is not 100% correct: #2897533: Documentation and example for FileCopy is wrong