dcache-frontend: add documentation concerning restores

Motivation:

    It is currently unclear (at least it is not explicitly
    documented) what the 'restores' API corresponds to.
    In particular, users may get the impression that
    the tape restores should also include requests
    initiated using the pool command 'rh restore <pnfsid>'.

Modification:

    Add statement in SWAGGER documentation for the
    restores API path explaining the difference between the
    restores page and an API request for the stage
    queue on a pool.

Result:

    Confusion hopefully mitigated.

    Target: master
    Request: 5.0
    Request: 4.2
    Request: 4.1
    Acked-by: Olufemi
    Acked-by: Paul

modules/dcache-frontend/src/main/java/org/dcache/restful/resources/restores/RestoreResources.java

@@ -96,8 +96,14 @@ public final class RestoreResources {
     private RestoresInfoService service;
 
     @GET
-    @ApiOperation("Obtain a (potentially partial) list of restore operations "
-            + "from some snapshot, along with a token that identifies the snapshot.")
+    @ApiOperation("Obtain a (potentially partial) list of restore operations"
+            + " from some snapshot, along with a token that identifies the snapshot.  Note:"
+                    + " the output to this request represents all the staging operations"
+                    + " triggered through the pool manager (via read requests through"
+                    + " the doors); cf the admin command '\\sp rc ls'.  Stage operations"
+                    + " initiated directly on a pool via 'rh restore <pnfsid>' do not"
+                    + " appear here.  To see a listing of all stages/restores on a given"
+                    + " pool, use the API for /pools/{pool}/nearline/queues?type=stage).")
     @ApiResponses({
                 @ApiResponse(code = 500, message = "Internal Server Error"),
             })