added some comments

fda-citation-service/services/src/main/java/at/tuwien/service/FileService.java

@@ -11,14 +11,62 @@ import java.util.List;
 @Service
 public interface FileService {
 
+    /**
+     * Upload a new file to a remote server for a given database-table id pair and metadata
+     *
+     * @param databaseId The database-table id paid
+     * @param tableId    The database-table id pair
+     * @param data       The metadata
+     * @param resource   The file
+     * @return The new file
+     * @throws ZenodoAuthenticationException     Token invalid
+     * @throws ZenodoApiException                Something other went wrong
+     * @throws ZenodoNotFoundException           The deposit id was not found on the remote server
+     * @throws ZenodoFileTooLargeException       The file exceeds the capabilities
+     * @throws MetadataDatabaseNotFoundException The deposit was not found on the metadata database
+     */
     FileResponseDto createResource(Long databaseId, Long tableId, FileUploadDto data, File resource)
             throws ZenodoAuthenticationException, ZenodoApiException, ZenodoNotFoundException,
             ZenodoFileTooLargeException, MetadataDatabaseNotFoundException;
 
+    /**
+     * List all files known to a deposit number (through the database-table id pair)
+     *
+     * @param databaseId The database-table id pair
+     * @param tableId    The database-table id pair
+     * @return The list of files
+     * @throws ZenodoAuthenticationException     Token invalid
+     * @throws ZenodoApiException                Something other went wrong
+     * @throws ZenodoNotFoundException           The deposit id was not found on the remote server
+     * @throws MetadataDatabaseNotFoundException The deposit was not found on the metadata database
+     */
     List<FileResponseDto> listResources(Long databaseId, Long tableId) throws MetadataDatabaseNotFoundException, ZenodoAuthenticationException, ZenodoNotFoundException, ZenodoApiException;
 
+    /**
+     * Find a file for a deposit (through the database-table id pair) by id
+     *
+     * @param databaseId The database-table id pair
+     * @param tableId    The database-table id pair
+     * @param fileId     The file id
+     * @return The file
+     * @throws MetadataDatabaseNotFoundException The deposit was not found on the metadata database
+     * @throws ZenodoAuthenticationException     Token invalid
+     * @throws ZenodoNotFoundException           The deposit id was not found on the remote server
+     * @throws ZenodoApiException                Something other went wrong
+     */
     FileResponseDto findResource(Long databaseId, Long tableId, String fileId) throws MetadataDatabaseNotFoundException, ZenodoAuthenticationException, ZenodoNotFoundException, ZenodoApiException;
 
+    /**
+     * Delete a file based on the database-table id pair by id
+     *
+     * @param databaseId The database-table id pair
+     * @param tableId    The database-table id pair
+     * @param fileId     The file id
+     * @throws MetadataDatabaseNotFoundException The deposit was not found on the metadata database
+     * @throws ZenodoAuthenticationException     Token invalid
+     * @throws ZenodoNotFoundException           The deposit id was not found on the remote server
+     * @throws ZenodoApiException                Something other went wrong
+     */
     void deleteResource(Long databaseId, Long tableId, String fileId)
             throws MetadataDatabaseNotFoundException, ZenodoAuthenticationException, ZenodoNotFoundException,
             ZenodoApiException;

fda-citation-service/services/src/main/java/at/tuwien/service/MetadataService.java

@@ -10,12 +10,44 @@ import java.util.List;
 
 @Service
 public interface MetadataService {
+
+    /**
+     * List all deposits (e.g. datasets) available
+     *
+     * @return The deposists
+     * @throws ZenodoAuthenticationException Token invalid
+     * @throws ZenodoApiException            Something other went wrong
+     */
     List<DepositResponseDto> listCitations() throws ZenodoAuthenticationException, ZenodoApiException;
 
+    /**
+     * Create a new deposit
+     *
+     * @return The created deposit
+     * @throws ZenodoAuthenticationException Token invalid
+     * @throws ZenodoApiException            Something other went wrong
+     */
     DepositChangeResponseDto storeCitation() throws ZenodoAuthenticationException, ZenodoApiException;
 
+    /**
+     * Update a deposit with new metadata for a given id
+     *
+     * @param id   The id
+     * @param data The new metadata
+     * @return The updated deposit
+     * @throws ZenodoAuthenticationException Token invalid
+     * @throws ZenodoApiException            Something other went wrong
+     * @throws ZenodoNotFoundException       The deposit id was not found on the remote server
+     */
     DepositChangeResponseDto updateCitation(Long id, DepositChangeRequestDto data) throws ZenodoAuthenticationException,
             ZenodoApiException, ZenodoNotFoundException;
 
+    /**
+     * Delete a deposit from a given id
+     *
+     * @param id The id
+     * @throws ZenodoAuthenticationException Token invalid
+     * @throws ZenodoApiException            Something other went wrong
+     */
     void deleteCitation(Long id) throws ZenodoAuthenticationException, ZenodoApiException;
 }