Added JavaDocs to main class

Author: burdoto

src/main/java/io/codebottle/api/CodeBottle.java

@@ -6,7 +6,6 @@
 import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.CompletionStage;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.stream.Collectors;
 import java.util.stream.StreamSupport;
@@ -21,32 +20,71 @@
 import okhttp3.OkHttpClient;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * API Class. Create an instance of this using {@link #builder()} to use the API.
+ */
 @Builder
 public final class CodeBottle {
-    public final CompletionStage<Void> lazyLoading = CompletableFuture.allOf(requestLanguages(), requestCategories());
-
     private final Map<String, Language> languageCache = new ConcurrentHashMap<>();
     private final Map<String, Category> categoryCache = new ConcurrentHashMap<>();
     private final Map<String, Snippet> snippetCache = new ConcurrentHashMap<>();
-    
     @Builder.Default
     private final @Nullable String token = null;
     @Builder.Default
     private @Getter final OkHttpClient httpClient = new OkHttpClient.Builder().build();
+    /**
+     * A {@link CompletableFuture} that completes once lazy loading was finished.
+     * <p>
+     * Lazy loading is calling {@link #requestLanguages()} and {@link #requestCategories()} on API construction.
+     */
+    public final CompletableFuture<Void> lazyLoading = CompletableFuture.allOf(requestLanguages(), requestCategories());
+
+    /**
+     * Waits for {@linkplain #lazyLoading lazy loading} to finish using {@link CompletableFuture#join()}.
+     * This method is intended to be used for API chaining, otherwise it is recommended to wait for {@link #lazyLoading} yourself.
+     *
+     * @return this {@link CodeBottle} instance.
+     */
+    public CodeBottle waitForLazyLoading() {
+        lazyLoading.join();
+
+        return this;
+    }
 
     @SuppressWarnings("ConstantConditions")
     public Optional<String> getToken() {
         return Optional.ofNullable(token);
     }
 
+    /**
+     * Returns the {@link Language} matching the given {@code id} if found.
+     * Before {@link #lazyLoading} was completed, this will always return {@link Optional#empty()}.
+     *
+     * @param id is the ID of the desired language.
+     *
+     * @return the language matching the given {@code id}.
+     */
     public Optional<Language> getLanguageByID(String id) {
         return Optional.ofNullable(languageCache.get(id));
     }
 
+    /**
+     * Returns all cached {@link Language}s.
+     * Before {@link #lazyLoading} was completed, the returned {@link Collection} will always be empty.
+     *
+     * @return a {@link Collection} of all cached languages.
+     */
     public Collection<Language> getLanguages() {
         return languageCache.values();
     }
 
+    /**
+     * Requests the language by the given {@code id} and synchronizes the cache when deserializing the result.
+     *
+     * @param id is the {@code id} of the {@link Language} to request.
+     *
+     * @return a future that will complete with the requested {@link Language} after updating it in the cache.
+     */
     public CompletableFuture<Language> requestLanguageByID(String id) {
         return new CodeBottleRequest<Language>(this)
                 .to(Endpoint.LANGUAGE_SPECIFIC, id)
@@ -62,6 +100,11 @@ public CompletableFuture<Language> requestLanguageByID(String id) {
                 });
     }
 
+    /**
+     * Requests all {@link Language}s and refreshes them in the cache.
+     *
+     * @return a future that will complete with all cached {@link Language}s.
+     */
     public CompletableFuture<Collection<Language>> requestLanguages() {
         return new CodeBottleRequest<Collection<Language>>(this)
                 .to(Endpoint.LANGUAGES)
@@ -83,14 +126,35 @@ public CompletableFuture<Collection<Language>> requestLanguages() {
                 });
     }
 
+    /**
+     * Returns the {@link Category} matching the given {@code id} if found in cache.
+     * Before {@link #lazyLoading} was completed, this will always return {@link Optional#empty()}.
+     *
+     * @param id is the ID of the desired category.
+     *
+     * @return the category matching the given {@code id}.
+     */
     public Optional<Category> getCategoryByID(String id) {
         return Optional.ofNullable(categoryCache.get(id));
     }
 
+    /**
+     * Returns all cached {@linkplain Category categories}.
+     * Before {@link #lazyLoading} was completed, the returned {@link Collection} will always be empty.
+     *
+     * @return a {@link Collection} of all cached categories.
+     */
     public Collection<Category> getCategories() {
         return categoryCache.values();
     }
 
+    /**
+     * Requests the category by the given {@code id} and synchronizes the cache when deserializing the result.
+     *
+     * @param id is the {@code id} of the {@link Category} to request.
+     *
+     * @return a future that will complete with the requested {@link Category} after updating it in the cache.
+     */
     public CompletableFuture<Category> requestCategoryByID(String id) {
         return new CodeBottleRequest<Category>(this)
                 .to(Endpoint.CATEGORY_SPECIFIC, id)
@@ -106,6 +170,11 @@ public CompletableFuture<Category> requestCategoryByID(String id) {
                 });
     }
 
+    /**
+     * Requests all {@link Category}s and refreshes them in the cache.
+     *
+     * @return a future that will complete with all cached {@linkplain Category categories}.
+     */
     public CompletableFuture<Collection<Category>> requestCategories() {
         return new CodeBottleRequest<Collection<Category>>(this)
                 .to(Endpoint.CATEGORIES)
@@ -127,14 +196,33 @@ public CompletableFuture<Collection<Category>> requestCategories() {
                 });
     }
 
+    /**
+     * Returns the {@link Snippet} matching the given {@code id} if found.
+     *
+     * @param id is the ID of the desired snippet.
+     *
+     * @return the snippet matching the given {@code id}.
+     */
     public Optional<Snippet> getSnippetByID(String id) {
         return Optional.ofNullable(snippetCache.get(id));
     }
 
+    /**
+     * Returns all cached {@link Snippet}s.
+     *
+     * @return a {@link Collection} of all cached snippets.
+     */
     public Collection<Snippet> getSnippets() {
         return snippetCache.values();
     }
 
+    /**
+     * Requests the snippet by the given {@code id} and synchronizes the cache when deserializing the result.
+     *
+     * @param id is the {@code id} of the {@link Snippet} to request.
+     *
+     * @return a future that will complete with the requested {@link Snippet} after updating it in the cache.
+     */
     public CompletableFuture<Snippet> requestSnippetByID(String id) {
         return new CodeBottleRequest<Snippet>(this)
                 .to(Endpoint.SNIPPET_SPECIFIC, id)
@@ -150,6 +238,11 @@ public CompletableFuture<Snippet> requestSnippetByID(String id) {
                 });
     }
 
+    /**
+     * Requests all {@link Snippet}s and refreshes them in the cache.
+     *
+     * @return a future that will complete with all cached {@link Snippet}s.
+     */
     public CompletableFuture<Collection<Snippet>> requestSnippets() {
         return new CodeBottleRequest<Collection<Snippet>>(this)
                 .to(Endpoint.SNIPPETS)
@@ -171,40 +264,70 @@ public CompletableFuture<Collection<Snippet>> requestSnippets() {
                 });
     }
 
+    /**
+     * Returns the {@link Snippet.Revision} matching the given {@code id pair} if found in cache.
+     * Before this method will ever not return {@link Optional#empty()}, you must {@linkplain #requestAllRevisions() request all revisions}.
+     *
+     * @param id is the ID of the desired language.
+     *
+     * @return the language matching the given {@code id}.
+     */
     public Optional<Snippet.Revision> getSnippetRevisionByID(String snippetId, int id) throws IndexOutOfBoundsException {
         return Optional.ofNullable(snippetCache.get(snippetId))
                 .flatMap(snippet -> snippet.getRevisionByID(id));
     }
 
+    /**
+     * Returns all cached {@link Language}s.
+     *
+     * @return a {@link Collection} of all cached languages.
+     */
     public Collection<Snippet.Revision> getSnippetRevisions() {
         return snippetCache.values()
                 .stream()
                 .flatMap(snippet -> snippet.getRevisions().stream())
                 .collect(Collectors.toList());
     }
 
+    /**
+     * Requests the snippet revision by the given {@code id} and synchronizes the cache when deserializing the result.
+     *
+     * @param id is the {@code id} of the {@link Snippet.Revision} to request.
+     *
+     * @return a future that will complete with the requested {@link Snippet.Revision} after updating it in the cache.
+     */
     public CompletableFuture<Snippet.Revision> requestSnippetRevisionByID(String snippetId, int id) {
         return getSnippetByID(snippetId)
                 .orElseGet(() -> requestSnippetByID(snippetId).join())
                 .requestRevision(id);
     }
 
-    public CompletableFuture<List<Snippet.Revision>> requestSnippetRevisions(String snippetId, int id) {
+    /**
+     * Requests all {@link Snippet.Revision}s of the defined {@linkplain Snippet snippet id} and refreshes them in the cache.
+     *
+     * @return a future that will complete with all cached {@link Snippet.Revision}s.
+     */
+    public CompletableFuture<List<Snippet.Revision>> requestSnippetRevisions(String snippetId) {
         return getSnippetByID(snippetId)
                 .orElseGet(() -> requestSnippetByID(snippetId).join())
                 .requestRevisions();
     }
-    
+
+    /**
+     * Requests all {@link Snippet.Revision}s and refreshes them in the cache.
+     *
+     * @return a future that will complete with all cached {@link Snippet.Revision}s.
+     */
     public CompletableFuture<Collection<Snippet.Revision>> requestAllRevisions() {
         return requestSnippets()
                 .thenApply(snippets -> {
                     Collection<Snippet.Revision> yields = new ArrayList<>();
-                    
+
                     (snippets.size() > 200 ? snippets.parallelStream() : snippets.stream())
                             .map(Snippet::requestRevisions)
                             .map(CompletableFuture::join)
                             .forEach(yields::addAll);
-                    
+
                     return yields;
                 });
     }