From f7a424e7aebe58b83c0d3941bd7e4eca423fa41e Mon Sep 17 00:00:00 2001
From: Oshgnacknak <osh@oshgnacknak.de>
Date: Sun, 29 Aug 2021 21:26:11 +0200
Subject: [PATCH] Document some of SequenceProcessor's methods

---
 src/aud/exam/prep/SequenceProcessor.java | 35 ++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/src/aud/exam/prep/SequenceProcessor.java b/src/aud/exam/prep/SequenceProcessor.java
index f73372a..f2d2636 100644
--- a/src/aud/exam/prep/SequenceProcessor.java
+++ b/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);
 }