Enhance class & function documentation in LFUcache.java

src/main/java/com/thealgorithms/datastructures/caches/LFUCache.java

@@ -4,18 +4,41 @@
 import java.util.Map;
 
 /**
- * Java program for LFU Cache (https://en.wikipedia.org/wiki/Least_frequently_used)
+ * The {@code LFUCache} class implements a Least Frequently Used (LFU) cache.
+ * An LFU cache evicts the least frequently used item when the cache reaches its capacity.
+ * It keeps track of how many times each item is used and maintains a doubly linked list
+ * for efficient addition and removal of items based on their frequency of use.
+ *
+ * @param <K> The type of keys maintained by this cache.
+ * @param <V> The type of mapped values.
+ *
+ * <p>
+ * Reference: <a href="https://en.wikipedia.org/wiki/Least_frequently_used">LFU Cache - Wikipedia</a>
+ * </p>
+ *
  * @author Akshay Dubey (https://github.com/itsAkshayDubey)
  */
 public class LFUCache<K, V> {
 
+    /**
+     * The {@code Node} class represents an element in the LFU cache.
+     * Each node contains a key, a value, and a frequency count.
+     * It also has pointers to the previous and next nodes in the doubly linked list.
+     */
     private class Node {
         private final K key;
         private V value;
         private int frequency;
         private Node previous;
         private Node next;
 
+        /**
+         * Constructs a new {@code Node} with the specified key, value, and frequency.
+         *
+         * @param key The key associated with this node.
+         * @param value The value stored in this node.
+         * @param frequency The frequency of usage of this node.
+         */
         Node(K key, V value, int frequency) {
             this.key = key;
             this.value = value;
@@ -29,10 +52,19 @@ private class Node {
     private final int capacity;
     private static final int DEFAULT_CAPACITY = 100;
 
+    /**
+     * Constructs an LFU cache with the default capacity.
+     */
     public LFUCache() {
         this(DEFAULT_CAPACITY);
     }
 
+    /**
+     * Constructs an LFU cache with the specified capacity.
+     *
+     * @param capacity The maximum number of items that the cache can hold.
+     * @throws IllegalArgumentException if the specified capacity is less than or equal to zero.
+     */
     public LFUCache(int capacity) {
         if (capacity <= 0) {
             throw new IllegalArgumentException("Capacity must be greater than zero.");
@@ -42,10 +74,12 @@ public LFUCache(int capacity) {
     }
 
     /**
-     * Retrieves the value for the given key from the cache. Increases the frequency of the node.
+     * Retrieves the value associated with the given key from the cache.
+     * If the key exists, the node's frequency is increased and the node is repositioned
+     * in the linked list based on its updated frequency.
      *
-     * @param key The key to look up.
-     * @return The value associated with the key, or null if the key is not present.
+     * @param key The key whose associated value is to be returned.
+     * @return The value associated with the key, or {@code null} if the key is not present in the cache.
      */
     public V get(K key) {
         Node node = cache.get(key);
@@ -59,10 +93,12 @@ public V get(K key) {
     }
 
     /**
-     * Adds or updates a key-value pair in the cache. If the cache is full, the least frequently used item is evicted.
+     * Inserts or updates a key-value pair in the cache.
+     * If the key already exists, the value is updated and its frequency is incremented.
+     * If the cache is full, the least frequently used item is removed before inserting the new item.
      *
-     * @param key   The key to insert or update.
-     * @param value The value to insert or update.
+     * @param key The key associated with the value to be inserted or updated.
+     * @param value The value to be inserted or updated.
      */
     public void put(K key, V value) {
         if (cache.containsKey(key)) {
@@ -73,7 +109,7 @@ public void put(K key, V value) {
             addNodeWithUpdatedFrequency(node);
         } else {
             if (cache.size() >= capacity) {
-                cache.remove(this.head.key);
+                cache.remove(this.head.key); // Evict least frequently used item
                 removeNode(head);
             }
             Node node = new Node(key, value, 1);
@@ -84,8 +120,9 @@ public void put(K key, V value) {
 
     /**
      * Adds a node to the linked list in the correct position based on its frequency.
+     * The linked list is ordered by frequency, with the least frequently used node at the head.
      *
-     * @param node The node to add.
+     * @param node The node to be inserted into the list.
      */
     private void addNodeWithUpdatedFrequency(Node node) {
         if (tail != null && head != null) {
@@ -122,9 +159,10 @@ private void addNodeWithUpdatedFrequency(Node node) {
     }
 
     /**
-     * Removes a node from the linked list.
+     * Removes a node from the doubly linked list.
+     * This method ensures that the pointers of neighboring nodes are properly updated.
      *
-     * @param node The node to remove.
+     * @param node The node to be removed from the list.
      */
     private void removeNode(Node node) {
         if (node.previous != null) {