[gparted] Document workings of calibrate_partition() method

[Curtis Gedak <gedakc src gnome org>]

commit b293a464cbcaf446eed204bf9e84183e518f58e0
Author: Mike Fleetwood <mike fleetwood googlemail com>
Date:   Tue Jan 13 17:01:51 2015 +0000

    Document workings of calibrate_partition() method
    
    Document the reasons why GParted_Core::calibrate_partition() needs to
    reload the device name and partition boundaries from libparted.

 src/GParted_Core.cc |   26 ++++++++++++++++++++++++++
 1 files changed, 26 insertions(+), 0 deletions(-)
---
diff --git a/src/GParted_Core.cc b/src/GParted_Core.cc
index d52ead2..945f85e 100644
--- a/src/GParted_Core.cc
+++ b/src/GParted_Core.cc
@@ -3167,8 +3167,34 @@ bool GParted_Core::calibrate_partition( Partition & partition, OperationDetail &
                
                        if ( lp_partition )//FIXME: add check to see if lp_partition ->type matches partition 
.type..
                        {
+                               // Re-add the real partition path from libparted.
+                               //
+                               // When creating a copy operation the list of paths for
+                               // the partition object was set to ["copy of /dev/SRC"] to
+                               // display in the UI before the operations are applied.
+                               // When pasting into an existing partition, this re-adds
+                               // the real path to the start of the list making it
+                               // ["/dev/DST", "copy of /dev/SRC"].  This provides the
+                               // real path for any file system specific tools needed
+                               // during the copy operation.  Such as file system check
+                               // and grow steps added when the source and destination
+                               // aren't identical sizes or when file system specific
+                               // tools are used to perform the copy as for XFS or recent
+                               // EXT2/3/4 tools.
+                               //
+                               // FIXME: Having this work just because "/dev/DST" happens
+                               // to sort before "copy of /dev/SRC" is ugly!  Probably
+                               // have a separate display path which can be changed at
+                               // will without affecting the list of real paths for the
+                               // partition.
                                partition .add_path( get_partition_path( lp_partition ) ) ;
 
+                               // Reload the partition boundaries from libparted to
+                               // ensure that GParted knows what the actual partition
+                               // boundaries are before applying the next operation.
+                               // Necessary when the previous operation in the sequence
+                               // was a resize/move operation where GParted may have only
+                               // estimated where libparted would move the boundaries to.
                                partition .sector_start = lp_partition ->geom .start ;
                                partition .sector_end = lp_partition ->geom .end ;