Merge pull request kitodo#6162 from stweil/javadoc

Fix javadoc errors and warnings for Kitodo-API

Kitodo-API/src/main/java/org/kitodo/api/dataeditor/DataEditorInterface.java

@@ -26,6 +26,7 @@ public interface DataEditorInterface {
      *            The URI to the xml file to read.
      * @param xsltFileUri
      *            The URI to the xsl file for transformation of old format goobi metadata files.
+     * @throws IOException if reading fails.
      */
     void readData(URI xmlFileUri, URI xsltFileUri) throws IOException;
 

Kitodo-API/src/main/java/org/kitodo/api/dataeditor/rulesetmanagement/MetadataViewWithValuesInterface.java

@@ -24,7 +24,7 @@
  * for this key. If the key is a multiple choice, the values are grouped, hence
  * the list, otherwise the length of the list is always only one. Effectively,
  * the return type of
- * {@link ComplexMetadataViewInterface#getSortedVisibleMetadatas(Collection, Collection)}
+ * {@link ComplexMetadataViewInterface#getSortedVisibleMetadata(Collection, Collection)}
  * is {@code List<Pair<MetadataViewInterface, Collection<T>>>}. Since the key
  * must be repeatable if there is more than one value but the key is not a
  * multiple choice, a map would be an inappropriate choice at this point.

Kitodo-API/src/main/java/org/kitodo/api/dataformat/MediaPartial.java

@@ -28,8 +28,7 @@ public class MediaPartial {
      * Constructs a media partial object.
      *
      * @param begin
-     *         The begin as formatted time in form of
-     *         {@link org.kitodo.production.helper.metadata.MediaPartialHelper#FORMATTED_TIME_PATTERN}
+     *         The begin as formatted time.
      */
     public MediaPartial(String begin) {
         this.begin = begin;
@@ -39,11 +38,9 @@ public MediaPartial(String begin) {
      * Constructs a media partial object.
      *
      * @param begin
-     *         The begin as formatted time in form of
-     *         {@link org.kitodo.production.helper.metadata.MediaPartialHelper#FORMATTED_TIME_PATTERN}
+     *         The begin as formatted time.
      * @param extent
-     *         The extent as formatted time in form of
-     *         {@link org.kitodo.production.helper.metadata.MediaPartialHelper#FORMATTED_TIME_PATTERN}
+     *         The extent as formatted time.
      */
     public MediaPartial(String begin, String extent) {
         this(begin);

Kitodo-API/src/main/java/org/kitodo/api/filemanagement/FileManagementInterface.java

@@ -35,6 +35,7 @@ public interface FileManagementInterface {
      * @param file
      *            if true it creates the file, if false it created directory
      * @return the URI of the new resource
+     * @throws IOException if file/folder could not be created
      */
     URI create(URI parentFolderUri, String name, boolean file) throws IOException;
 
@@ -44,6 +45,7 @@ public interface FileManagementInterface {
      * @param uri
      *            the uri to write to
      * @return an writable OutputStream
+     * @throws IOException if uri could not be written
      */
     OutputStream write(URI uri) throws IOException;
 
@@ -53,6 +55,7 @@ public interface FileManagementInterface {
      * @param uri
      *            the uri to write from
      * @return a readable InputStream
+     * @throws IOException if uri could not be read
      */
     InputStream read(URI uri) throws IOException;
 
@@ -63,6 +66,7 @@ public interface FileManagementInterface {
      *            source file as uri
      * @param targetResource
      *            destination file as uri
+     * @throws IOException if source could not be read or destination could not be written
      */
     void copy(URI sourceResource, URI targetResource) throws IOException;
 
@@ -72,6 +76,7 @@ public interface FileManagementInterface {
      * @param uri
      *            the URI to delete
      * @return true if successful, false otherwise
+     * @throws IOException if uri could not be deleted
      */
     boolean delete(URI uri) throws IOException;
 
@@ -95,6 +100,7 @@ public interface FileManagementInterface {
      * @param newName
      *            the new name of the resource
      * @return URI of renamed resource
+     * @throws IOException if uri could not be renamed
      */
     URI rename(URI uri, String newName) throws IOException;
 
@@ -114,6 +120,7 @@ public interface FileManagementInterface {
      * @param directory
      *            URI to get size
      * @return size of directory as Long
+     * @throws IOException if getting the size of URI failed
      */
     Long getSizeOfDirectory(URI directory) throws IOException;
 
@@ -179,6 +186,7 @@ public interface FileManagementInterface {
      * @param processId
      *            the id of the process
      * @return the URI to the process Location
+     * @throws IOException if the folder structure could not be created
      */
     URI createProcessLocation(String processId) throws IOException;
 

Kitodo-API/src/main/java/org/kitodo/config/OPACConfig.java

@@ -71,6 +71,7 @@ private OPACConfig() {
      * @param catalogName String identifying the catalog by title
      * @param parameter String identifying the parameter by name
      * @return value of parameter
+     * @throws ParameterNotFoundException if parameter was not found
      */
     public static String getConfigValue(String catalogName, String parameter) throws ParameterNotFoundException {
         HierarchicalConfiguration<ImmutableNode> opacConfiguration = getCatalog(catalogName);
@@ -151,6 +152,7 @@ private static String getUrlConfigPart(String catalogName, String parameter)
      * Get host parameter of catalog configuration with name 'catalogName'.
      * @param catalogName name of catalog configuration
      * @return host value as String
+     * @throws MandatoryParameterMissingException if required parameter is missing
      */
     public static String getHost(String catalogName) throws MandatoryParameterMissingException {
         return getUrlConfigPart(catalogName, HOST);
@@ -160,6 +162,7 @@ public static String getHost(String catalogName) throws MandatoryParameterMissin
      * Get scheme parameter of catalog configuration with name 'catalogName'.
      * @param catalogName name of catalog configuration
      * @return scheme value as String
+     * @throws MandatoryParameterMissingException if required parameter is missing
      */
     public static String getScheme(String catalogName) throws MandatoryParameterMissingException {
         return getUrlConfigPart(catalogName, SCHEME);
@@ -169,6 +172,7 @@ public static String getScheme(String catalogName) throws MandatoryParameterMiss
      * Get path parameter of catalog configuration with name 'catalogName'.
      * @param catalogName name of catalog configuration
      * @return path value as String
+     * @throws MandatoryParameterMissingException if required parameter is missing
      */
     public static String getPath(String catalogName) throws MandatoryParameterMissingException {
         return getUrlConfigPart(catalogName, PATH);
@@ -178,6 +182,7 @@ public static String getPath(String catalogName) throws MandatoryParameterMissin
      * Get port parameter of catalog configuration with name 'catalogName'.
      * @param catalogName name of catalog configuration
      * @return port value as String
+     * @throws MandatoryParameterMissingException if required parameter is missing
      */
     public static String getPort(String catalogName) throws MandatoryParameterMissingException {
         return getUrlConfigPart(catalogName, PORT);

Kitodo-API/src/main/java/org/kitodo/config/enums/KitodoConfigFile.java

@@ -85,6 +85,7 @@ public String getAbsolutePath() {
      * @param name
      *            of configuration file
      * @return File
+     * @throws FileNotFoundException if the configuration file is not found
      */
     public static KitodoConfigFile getByName(String name) throws FileNotFoundException {
         for (KitodoConfigFile file : KitodoConfigFile.values()) {

Kitodo-API/src/main/java/org/kitodo/exceptions/UnknownTreeNodeDataException.java

@@ -15,6 +15,7 @@ public class UnknownTreeNodeDataException extends RuntimeException {
 
     /**
      * Constructor with given parameter name for exception message.
+     * @param type String which describes the unexpected type
      */
     public UnknownTreeNodeDataException(String type) {
         super("TreeNode contains data of unexpected type '" + type + "!");