docs: explain why replace operation is useful

#61 (review)

ipfs-pinning-service.yaml

@@ -77,7 +77,7 @@ In this case, the user can periodically check pinning progress via `GET /pins/{i
 
 ### Replacing an existing pin object
 
-The user can replace an existing pin object via `POST /pins/{id}`. This is a shortcut for removing a pin object identified by `id` and creating a new one in a single API call. The new pin object `id` is returned in the `PinStatus` response. The old pin object is deleted automatically.
+The user can replace an existing pin object via `POST /pins/{id}`. This is a shortcut for removing a pin object identified by `id` and creating a new one in a single API call that protects against undesired garbage collection of blocks common to both pins. Useful when updating a pin representing a huge dataset where most of blocks did not change. The new pin object `id` is returned in the `PinStatus` response. The old pin object is deleted automatically.
 
 
 ### Removing a pin object
@@ -256,7 +256,7 @@ paths:
           $ref: '#/components/responses/InternalServerError'
     post:
       summary: Replace pin object
-      description: Replace an existing pin object (shortcut for executing both remove and add in one step)
+      description: Replace an existing pin object (shortcut for executing remove and add operations in one step to avoid unnecessary garbage collection of blocks present in both recursive pins)
       tags:
         - pins
       requestBody: