From fab83cb4fc13040fe779fb1b86bba63054a6ed4c Mon Sep 17 00:00:00 2001
From: Eduardo Pinho <eduardopinho@bmd-software.com>
Date: Fri, 21 Jul 2023 10:56:34 +0100
Subject: [PATCH] [sdk] Improve StorageInterface documentation

- Fix example code in #at
- Clarify in #list that a trailing forward slash
  means that it's a directory
---
 .../pt/ua/dicoogle/sdk/StorageInterface.java     | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/sdk/src/main/java/pt/ua/dicoogle/sdk/StorageInterface.java b/sdk/src/main/java/pt/ua/dicoogle/sdk/StorageInterface.java
index a4e08c16b..784f4b3b3 100644
--- a/sdk/src/main/java/pt/ua/dicoogle/sdk/StorageInterface.java
+++ b/sdk/src/main/java/pt/ua/dicoogle/sdk/StorageInterface.java
@@ -62,13 +62,16 @@ public default boolean handles(URI location) {
      * 
      * The provided scheme is not relevant at this point, but the developer must avoid calling this method
      * with a path of a different schema.
-     * 
-     * <pre>for(StorageInputStream dicomObj : storagePlugin.at("file://dataset/")){
-     *      System.err.println(dicomObj.getURI());
-     * }</pre>
+     *
+     * <pre>
+     * URI uri = URI.create("file://dataset/");
+     * for (StorageInputStream dicomObj: storagePlugin.at(uri)) {
+     *     System.err.println(dicomObj.getURI());
+     * }
+     * </pre>
      * 
      * @param location the location to read
-     * @param parameters a variable list of extra parameters for the retrieve
+     * @param parameters a variable list of extra retrieval parameters
      * @return an iterable of storage input streams
      * @see StorageInputStream
      */
@@ -139,6 +142,9 @@ default public StorageInputStream get(URI location, Object... parameters) {
      * can yield intermediate URIs representing other directories rather than
      * objects.
      * 
+     * Directories can be distinguished from regular files
+     * by the presence of a trailing forward slash in the URI.
+     * 
      * The provided scheme is not relevant at this point, but the developer
      * must avoid calling this method with a path of a different scheme.
      *