Document some of SequenceProcessor's methods

src/aud/exam/prep/SequenceProcessor.java

@@ -2,6 +2,14 @@ package aud.exam.prep;
 
 import java.util.Comparator;
 
+/**
+ * Instances of this interface can work with any "valid" sequences of type <code>S</code>.
+ * For what is valid, see {@link #check(S)}.
+ * This is a literal translation of the "inspiration sheet" into java.
+ *
+ * @param <T> Type of elements stored in <code>S</code>
+ * @param <S> Type of the sequence
+ */
 public interface SequenceProcessor<T, S> {
 
     boolean find(S s, T t);
@@ -26,8 +34,6 @@ public interface SequenceProcessor<T, S> {
 
     T secondMax(S s, Comparator<T> cmp);
 
-    boolean check(S s);
-
     boolean isItemWiseLessOrEqual(S a, S b, Comparator<T> cmp);
 
     boolean isItemWiseLess(S a, S b, Comparator<T> cmp);
@@ -62,7 +68,32 @@ public interface SequenceProcessor<T, S> {
 
     Pair<S, S> divideByPivot(S s, T pivot, Comparator<T> cmp);
 
+    /**
+     * Check whether ot not the given sequence is "valid" according to
+     * what is considered valid depends on the specific data structure.
+     * This is also used by the tests.
+     *
+     * @param s A sequence
+     * @return true iff the given sequence is valid
+     */
+    boolean check(S s);
+
+    /**
+     * Create a sequence from an {@link Iterable}.
+     * This is required by the tests.
+     *
+     * @param iterable An {@link Iterable}
+     * @return A sequence with the elements of the given iterable
+     */
     S create(Iterable<T> iterable);
 
+    /**
+     * Return an {@link Iterable}, or a lambda returning {@link java.util.Iterator},
+     * over the elements of the sequence <code>s</code>.
+     * This is required by the tests.
+     *
+     * @param s A sequence
+     * @return An {@link Iterable} over s
+     */
     Iterable<T> iterate(S s);
 }