Document StudentFileAwareZipper

Author: cxcorp

tmc-langs-framework/src/main/java/fi/helsinki/cs/tmc/langs/io/zip/StudentFileAwareZipper.java

@@ -16,6 +16,25 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 
+/**
+ * This {@link Zipper} implementation recursively zips the files of a directory.
+ * Only files considered to be student files by the specified {@link StudentFilePolicy}
+ * are included in the archive.
+ *
+ * <p>The {@link StudentFilePolicy} provided either via the
+ * {@link #StudentFileAwareZipper(StudentFilePolicy) constructor} or a
+ * {@link #setStudentFilePolicy(StudentFilePolicy) setter method} is used to determine whether
+ * a file or directory should be included in the archive.</p>
+ *
+ * <p>Individual directories can be excluded from archival by adding a file in the directory
+ * root with the name of {@code .tmcnosubmit}. For example, if the folder {@code sensitive/}
+ * should be excluded, the file {@code sensitive/.tmcnosubmit} should be created. The contents
+ * of the file are ignored.</p>
+ *
+ * <p>File system roots (e.g. {@code /} on *nix and {@code C:\} on Windows platforms) cannot
+ * be zipped, as this {@link Zipper} includes the specified {@code rootDirectory}
+ * in the zip file as a parent directory.</p>
+ */
 public final class StudentFileAwareZipper implements Zipper {
 
     private static final Logger log = LoggerFactory.getLogger(StudentFileAwareZipper.class);
@@ -24,17 +43,45 @@ public final class StudentFileAwareZipper implements Zipper {
 
     private StudentFilePolicy filePolicy;
 
+    /**
+     * Instantiates a new {@link StudentFileAwareZipper} without a {@link StudentFilePolicy}.
+     * The {@link #setStudentFilePolicy(StudentFilePolicy)} method can be used to set the policy.
+     */
     public StudentFileAwareZipper() {}
 
+    /**
+     * Instantiates a new {@link StudentFileAwareZipper} with the
+     * specified {@link StudentFilePolicy}.
+     *
+     * @param filePolicy Determines which files and directories are included in the archive.
+     * @see #setStudentFilePolicy(StudentFilePolicy)
+     */
     public StudentFileAwareZipper(StudentFilePolicy filePolicy) {
         this.filePolicy = filePolicy;
     }
 
+    /**
+     * Sets the {@link StudentFilePolicy} which determines which files and directories
+     * are included in the archive.
+     *
+     * @param studentFilePolicy Determines which files and directories are included in the archive.
+     * @see #StudentFileAwareZipper(StudentFilePolicy)
+     */
     @Override
     public void setStudentFilePolicy(StudentFilePolicy studentFilePolicy) {
         this.filePolicy = studentFilePolicy;
     }
 
+    /**
+     * Recursively zips all files and directories which are considered to be student files.
+     *
+     * @param rootDirectory The root directory of the files and directories to zip.
+     *                      Included in the archive. Cannot be a file system root.
+     * @return Byte array containing the bytes of the {@link ZipArchiveOutputStream}.
+     * @throws IOException if reading a file or directory fails.
+     * @throws IllegalArgumentException if attempting to zip a file system root.
+     * @see #setStudentFilePolicy(StudentFilePolicy)
+     */
     @Override
     public byte[] zip(Path rootDirectory) throws IOException {
         log.debug("Starting to zip {}", rootDirectory);