docs: Documented Skeleton

Author: Enginecrafter77

skeletonlayoutng/src/main/java/dev/enginecrafter77/skeletonlayoutng/Skeleton.java

@@ -16,8 +16,68 @@
  */
 package dev.enginecrafter77.skeletonlayoutng;
 
+import androidx.annotation.AnyThread;
+
+/**
+ * </p>Skeleton is an interface implemented by all classes facilitating the skeleton behavior.</p>
+ *
+ * <p>
+ *     In general, skeletons describe an element optimally with a captivating animation that captures
+ *     the user's attention while the underlying element is getting ready to be displayed with all it's
+ *     actual data. Skeletons should visually adhere to the View structure, so that given all skeletons are
+ *     showing, the actual layout composed from the skeletons is visually similar in structure to the actual
+ *     layout after all the skeletons are hidden. In simplest terms, a skeleton might just be a gray strip
+ *     covering TextView while the data that should be displayed by the TextView is being loaded.
+ * </p>
+ *
+ * <p>
+ *     All skeletons should implement 3 methods. {@link #showSkeleton()}, {@link #hideSkeleton()} and {@link #isActive()}.
+ *     These methods should be used to show the skeleton, hide it, and query it's current state respectively.
+ * </p>
+ *
+ * <p>
+ *     Upon skeleton creation, its state is undefined. Therefore, it is a good practice to call either {@link #showSkeleton()} or {@link #hideSkeleton()}
+ *     before the associated screen is displayed to the user.
+ * </p>
+ * @author Enginecrafter77
+ */
 public interface Skeleton {
-	public boolean isActive();
+	/**
+	 * <p>
+	 *     This method updates the skeleton so that the associated visual element is no longer visible,
+	 *     and instead of it there should be a "skeleton" showing (see the definition of skeleton in {@link Skeleton}).
+	 *     Further calls to this method should be idempotent.
+	 * </p>
+	 *
+	 * <p>
+	 *     Implementations of this method must take into account that there is no guarantee as to from
+	 *     which thread the call might originate. Therefore, it is highly advised to use {@link android.os.Handler}
+	 *     for any thread-sensitive work.
+	 * </p>
+	 */
+	@AnyThread
 	public void showSkeleton();
+
+	/**
+	 * <p>
+	 *     This method updates the skeleton so that the skeleton displayed over the visual element
+	 *     is dismissed and the underlying visual element becomes visible once more.
+	 *     Further calls to this method should be idempotent.
+	 * </p>
+	 *
+	 * <p>
+	 *     Implementations of this method must take into account that there is no guarantee as to from
+	 *     which thread the call might originate. Therefore, it is highly advised to use {@link android.os.Handler}
+	 *     for any thread-sensitive work.
+	 * </p>
+	 */
+	@AnyThread
 	public void hideSkeleton();
+
+	/**
+	 * Queries the state of the skeleton.
+	 * @return True if the skeleton is visible, false otherwise.
+	 */
+	@AnyThread
+	public boolean isActive();
 }