Cover some of commons functionality with documentation

DEVSIX-6382

Author: ars18wrw

commons/src/main/java/com/itextpdf/commons/actions/NamespaceConstant.java

@@ -47,6 +47,9 @@ This file is part of the iText (R) project.
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * Class that stores namespaces of iText open source products.
+ */
 public final class NamespaceConstant {
 
     public static final String ITEXT = "com.itextpdf";

commons/src/main/java/com/itextpdf/commons/actions/contexts/AbstractContextManagerConfigurationEvent.java

@@ -37,10 +37,21 @@ protected AbstractContextManagerConfigurationEvent() {
         super();
     }
 
+    /**
+     * Registers generic context for products and namespaces which are associated with them.
+     *
+     * @param namespaces namespaces of the products to be registered
+     * @param products the products to be registered
+     */
     protected void registerGenericContext(Collection<String> namespaces, Collection<String> products) {
         ContextManager.getInstance().registerGenericContext(namespaces, products);
     }
 
+    /**
+     * Unregisters certain namespaces.
+     *
+     * @param namespaces the namespaces to be unregisted
+     */
     protected void unregisterContext(Collection<String> namespaces) {
         ContextManager.getInstance().unregisterContext(namespaces);
     }

commons/src/main/java/com/itextpdf/commons/actions/contexts/UnknownContext.java

@@ -61,6 +61,11 @@ public class UnknownContext implements IContext {
 
     private final boolean allowEvents;
 
+    /**
+     * Creates a fallback {@link IContext}.
+     *
+     * @param allowEvents defines whether the context allows all events or not
+     */
     public UnknownContext(boolean allowEvents) {
         this.allowEvents = allowEvents;
     }

commons/src/main/java/com/itextpdf/commons/actions/processors/AbstractITextProductEventProcessor.java

@@ -25,10 +25,18 @@ This file is part of the iText (R) project.
 import com.itextpdf.commons.actions.AbstractProductProcessITextEvent;
 import com.itextpdf.commons.exceptions.CommonsExceptionMessageConstant;
 
+/**
+ * Abstract class with some standard functionality for product event processing.
+ */
 public abstract class AbstractITextProductEventProcessor implements ITextProductEventProcessor {
 
     private final String productName;
 
+    /**
+     * Creates a new instance of an abstract processor for the provided product.
+     *
+     * @param productName the product which will be handled by this processor
+     */
     public AbstractITextProductEventProcessor(String productName) {
         if (productName == null) {
             throw new IllegalArgumentException(CommonsExceptionMessageConstant.PRODUCT_NAME_CAN_NOT_BE_NULL);

commons/src/main/java/com/itextpdf/commons/utils/EncodingUtil.java

@@ -58,11 +58,19 @@ This file is part of the iText (R) project.
 public final class EncodingUtil {
     private static final String UTF8 = "UTF-8";
 
-
-
     private EncodingUtil() {
     }
 
+    /**
+     * Converts to byte array an array of chars, taking the provided encoding into account.
+     *
+     * @param chars an array of chars to be converted to bytes
+     * @param encoding the encoding to be taken into account while converting the provided array of chars
+     *
+     * @return the resultant array of bytes
+     *
+     * @throws CharacterCodingException if anything goes wrong while encoding
+     */
     public static byte[] convertToBytes(char[] chars, String encoding) throws CharacterCodingException {
         Charset cc = Charset.forName(encoding);
         CharsetEncoder ce = cc.newEncoder();
@@ -81,6 +89,16 @@ public static byte[] convertToBytes(char[] chars, String encoding) throws Charac
         return br;
     }
 
+    /**
+     * Converts to String an array of bytes, taking the provided encoding into account.
+     *
+     * @param bytes an array of bytes to be converted to String
+     * @param encoding the encoding to be taken into account while converting the provided bytes
+     *
+     * @return the resultant string
+     *
+     * @throws UnsupportedEncodingException if anything goes wrong while encoding
+     */
     public static String convertToString(byte[] bytes, String encoding) throws UnsupportedEncodingException {
         if (bytes[0] == (byte) 0xEF && bytes[1] == (byte) 0xBB
                 && bytes[2] == (byte) 0xBF && encoding.equals(EncodingUtil.UTF8)) {

commons/src/main/java/com/itextpdf/commons/utils/FileUtil.java

@@ -78,6 +78,11 @@ public final class FileUtil {
     private FileUtil() {
     }
 
+    /**
+     * Gets the default windows font directory.
+     *
+     * @return the default windows font directory
+     */
     public static String getFontsDir() {
         try {
             String winDir = System.getenv("windir");
@@ -90,6 +95,13 @@ public static String getFontsDir() {
         }
     }
 
+    /**
+     * Checks whether there is a file at the provided path.
+     *
+     * @param path the path to the file to be checked on existence
+     *
+     * @return {@code true} if such a file exists, otherwise {@code false}
+     */
     public static boolean fileExists(String path) {
         if (path != null) {
             File f = new File(path);
@@ -98,6 +110,14 @@ public static boolean fileExists(String path) {
         return false;
     }
 
+    /**
+     * Checks whether there is a directory at the provided path.
+     *
+     * @param path the path to the directory to be checked on existence
+     *
+     * @return {@code true} if such a directory exists, otherwise {@code false}
+     */
+
     public static boolean directoryExists(String path) {
         if (path != null) {
             File f = new File(path);
@@ -106,6 +126,14 @@ public static boolean directoryExists(String path) {
         return false;
     }
 
+    /**
+     * Lists all the files located at the provided directory.
+     *
+     * @param path path to the directory
+     * @param recursive if {@code true}, files from all the subdirectories will be returned
+     *
+     * @return all the files located at the provided directory
+     */
     public static String[] listFilesInDirectory(String path, boolean recursive) {
         if (path != null) {
             File root = new File(path);
@@ -129,6 +157,14 @@ public static String[] listFilesInDirectory(String path, boolean recursive) {
         return null;
     }
 
+    /**
+     * Lists all the files located at the provided directory, which are accepted by the provided filter.
+     *
+     * @param outPath  path to the directory
+     * @param fileFilter filter to accept files to be listed
+     *
+     * @return all the files located at the provided directory, which are accepted by the provided filter
+     */
     public static File[] listFilesInDirectoryByFilter(String outPath, FileFilter fileFilter) {
         File[] result = null;
         if (outPath != null && !outPath.isEmpty()) {
@@ -173,6 +209,16 @@ public static java.io.OutputStream wrapWithBufferedOutputStream(OutputStream out
         }
     }
 
+    /**
+     * Creates a temporary file at the provided path.
+     *
+     * @param path path to the temporary file to be created. If it is a directory, then the temporary file
+     *             will be created at this directory
+     *
+     * @return the created temporary file
+     *
+     * @throws IOException signals that an I/O exception has occurred
+     */
     public static File createTempFile(String path) throws IOException {
         File tempFile = new File(path);
         if (tempFile.isDirectory()) {
@@ -193,6 +239,11 @@ public static RandomAccessFile getRandomAccessFile(File tempFile) throws FileNot
         return new RandomAccessFile(tempFile, "rw");
     }
 
+    /**
+     * Creates a directory at the provided path.
+     *
+     * @param outPath path to the directory to be created
+     */
     public static void createDirectories(String outPath) {
         new File(outPath).mkdirs();
     }
@@ -298,7 +349,7 @@ public static String createTempDirectory(String tempFilePrefix)
      *
      * @param paths paths to files, which should be removed
      *
-     * @return true if all the files have been successfully removed, false otherwise
+     * @return {@code true} if all the files have been successfully removed, {@code false} otherwise
      */
     public static boolean removeFiles(String[] paths) {
         boolean allFilesAreRemoved = true;