docs: Update JSDoc

src/builder/CacheBuilder.ts

@@ -86,6 +86,10 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 	/**
 	 * Set a listener that will be called every time something is removed
 	 * from the cache.
+	 *
+	 * @param listener -
+	 *   removal listener to use
+	 * @returns self
 	 */
 	public withRemovalListener(listener: RemovalListener<K, V>) {
 		this.optRemovalListener = listener;
@@ -95,6 +99,10 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 	/**
 	 * Set the maximum number of items to keep in the cache before evicting
 	 * something.
+	 *
+	 * @param size -
+	 *   number of items to keep
+	 * @returns self
 	 */
 	public maxSize(size: number) {
 		this.optMaxSize = size;
@@ -103,6 +111,10 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 
 	/**
 	 * Set a function to use to determine the size of a cached object.
+	 *
+	 * @param weigher -
+	 *   function used to weight objects
+	 * @returns self
 	 */
 	public withWeigher(weigher: Weigher<K, V>) {
 		if(typeof weigher !== 'function') {
@@ -115,6 +127,8 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 	/**
 	 * Change to a cache where get can also resolve values if provided with
 	 * a function as the second argument.
+	 *
+	 * @returns self
 	 */
 	public loading(): LoadingCacheBuilder<K, V> {
 		return new LoadingCacheBuilderImpl(this, null);
@@ -123,6 +137,10 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 	/**
 	 * Change to a loading cache, where the get-method will return instances
 	 * of Promise and automatically load unknown values.
+	 *
+	 * @param loader -
+	 *   function used to load objects
+	 * @returns self
 	 */
 	public withLoader(loader: Loader<K, V>): LoadingCacheBuilder<K, V> {
 		if(typeof loader !== 'function') {
@@ -133,6 +151,11 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 
 	/**
 	 * Set that the cache should expire items after some time.
+	 *
+	 * @param time -
+	 *   max time in milliseconds, or function that will be asked per key/value
+	 *   for expiration time
+	 * @returns self
 	 */
 	public expireAfterWrite(time: number | MaxAgeDecider<K, V>) {
 		let evaluator;
@@ -149,6 +172,11 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 
 	/**
 	 * Set that the cache should expire items some time after they have been read.
+	 *
+	 * @param time -
+	 *   max time in milliseconds, or function will be asked per key/value
+	 *   for expiration time
+	 * @returns self
 	 */
 	public expireAfterRead(time: number | MaxAgeDecider<K, V>): this {
 		let evaluator;
@@ -165,6 +193,8 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 
 	/**
 	 * Activate tracking of metrics for this cache.
+	 *
+	 * @returns self
 	 */
 	public metrics(): this {
 		this.optMetrics = true;
@@ -173,6 +203,8 @@ export class CacheBuilderImpl<K extends KeyType, V> implements CacheBuilder<K, V
 
 	/**
 	 * Build and return the cache.
+	 *
+	 * @returns cache
 	 */
 	public build() {
 		let cache: Cache<K, V>;
@@ -282,6 +314,12 @@ class LoadingCacheBuilderImpl<K extends KeyType, V> implements LoadingCacheBuild
 	}
 }
 
+/**
+ * Helper function to create a weigher that uses an Expirable object.
+ *
+ * @param w -
+ * @returns weigher
+ */
 function createExpirableWeigher<K extends KeyType, V>(w: Weigher<K, V> | undefined): Weigher<K, Expirable<V>> | null {
 	if(! w) return null;
 

src/builder/index.ts

@@ -6,6 +6,9 @@ export { CacheBuilder, LoadingCacheBuilder } from './CacheBuilder';
 
 /**
  * Create a new cache via a builder.
+ *
+ * @returns
+ *   builder of a cache
  */
 export function newCache<K extends KeyType, V>(): CacheBuilder<K, V> {
 	return new CacheBuilderImpl<K, V>();

src/cache/Cache.ts

@@ -24,13 +24,25 @@ export interface Cache<K extends KeyType, V> {
 	/**
 	 * Store a value tied to the specified key. Returns the previous value or
 	 * `null` if no value currently exists for the given key.
+	 *
+	 * @param key -
+	 *   key to store value under
+	 * @param value -
+	 *   value to store
+	 * @returns
+	 *   current value or `null`
 	 */
 	set(key: K, value: V): V | null;
 
 	/**
 	 * Get the cached value for the specified key if it exists. Will return
 	 * the value or `null` if no cached value exist. Updates the usage of the
 	 * key.
+	 *
+	 * @param key -
+	 *   key to get
+	 * @returns
+	 *   current value or `null`
 	 */
 	getIfPresent(key: K): V | null;
 
@@ -41,24 +53,31 @@ export interface Cache<K extends KeyType, V> {
 	 *
 	 * In many cases `has(key)` is a better option to see if a key is present.
 	 *
-	 * @param key
+	 * @param key -
 	 *   the key to check
+	 * @returns
+	 *   value associated with key or `null`
 	 */
 	peek(key: K): V | null;
 
 	/**
 	 * Check if the given key exists in the cache.
 	 *
-	 * @param key
+	 * @param key -
+	 *   key to check
+	 * @returns
+	 *   `true` if value currently exists, `false` otherwise
 	 */
 	has(key: K): boolean;
 
 	/**
-	 * Delete a value in the cache. Returns the removed value or `null` if
+	 * Delete a value in the cache. Returns the deleted value or `null` if
 	 * there was no value associated with the key in the cache.
 	 *
-	 * @param key
+	 * @param key -
 	 *   the key to delete
+	 * @returns
+	 *   deleted value or `null`
 	 */
 	delete(key: K): V | null;
 
@@ -68,9 +87,13 @@ export interface Cache<K extends KeyType, V> {
 	clear(): void;
 
 	/**
-	 * Get all of the keys in the cache as an `Array`. Can be used to iterate
-	 * over all of the values in the cache, but be sure to protect against values
-	 * being removed during iteration due to time-based expiration if used.
+	 * Get all of the keys in the cache as an array. Can be used to iterate
+	 * over all of the values in the cache, but be sure to protect against
+	 * values being removed during iteration due to time-based expiration if
+	 * used.
+	 *
+	 * @returns
+	 *   snapshot of keys
 	 */
 	keys(): K[];
 

src/cache/CacheSPI.ts

@@ -8,7 +8,7 @@ import { ON_REMOVE, ON_MAINTENANCE } from './symbols';
  */
 export interface CacheSPI<K extends KeyType, V> {
 	/**
-	 * Called when a key is removed from the cache. Intended to be overriden
+	 * Called when a key is removed from the cache. Intended to be overridden
 	 * so that the value and removal reason can be modified.
 	 */
 	[ON_REMOVE]?: RemovalListener<K, V>;

src/cache/WrappedCache.ts

@@ -30,50 +30,147 @@ export abstract class WrappedCache<K extends KeyType, V> extends AbstractCache<K
 		this[PARENT][ON_REMOVE] = this[TRIGGER_REMOVE].bind(this);
 	}
 
+	/**
+	 * The maximum size the cache can be. Will be -1 if the cache is unbounded.
+	 *
+	 * @returns
+	 *   maximum size
+	 */
 	public get maxSize(): number {
 		return this[PARENT].maxSize;
 	}
 
+	/**
+	 * The current size of the cache.
+	 *
+	 * @returns
+	 *   current size
+	 */
 	public get size(): number {
 		return this[PARENT].size;
 	}
 
+	/**
+	 * The size of the cache weighted via the activate estimator.
+	 *
+	 * @returns
+	 *   current weighted size
+	 */
 	public get weightedSize(): number {
 		return this[PARENT].weightedSize;
 	}
 
+	/**
+	 * Store a value tied to the specified key. Returns the previous value or
+	 * `null` if no value currently exists for the given key.
+	 *
+	 * @param key -
+	 *   key to store value under
+	 * @param value -
+	 *   value to store
+	 * @returns
+	 *   current value or `null`
+	 */
 	public set(key: K, value: V): V | null {
 		return this[PARENT].set(key, value);
 	}
 
+	/**
+	 * Get the cached value for the specified key if it exists. Will return
+	 * the value or `null` if no cached value exist. Updates the usage of the
+	 * key.
+	 *
+	 * @param key -
+	 *   key to get
+	 * @returns
+	 *   current value or `null`
+	 */
 	public getIfPresent(key: K): V | null {
 		return this[PARENT].getIfPresent(key);
 	}
 
+	/**
+	 * Peek to see if a key is present without updating the usage of the
+	 * key. Returns the value associated with the key or `null`  if the key
+	 * is not present.
+	 *
+	 * In many cases `has(key)` is a better option to see if a key is present.
+	 *
+	 * @param key -
+	 *   the key to check
+	 * @returns
+	 *   value associated with key or `null`
+	 */
 	public peek(key: K): V | null {
 		return this[PARENT].peek(key);
 	}
 
+	/**
+	 * Check if the given key exists in the cache.
+	 *
+	 * @param key -
+	 *   key to check
+	 * @returns
+	 *   `true` if value currently exists, `false` otherwise
+	 */
 	public has(key: K): boolean {
 		return this[PARENT].has(key);
 	}
 
+	/**
+	 * Delete a value in the cache. Returns the deleted value or `null` if
+	 * there was no value associated with the key in the cache.
+	 *
+	 * @param key -
+	 *   the key to delete
+	 * @returns
+	 *   deleted value or `null`
+	 */
 	public delete(key: K): V | null {
 		return this[PARENT].delete(key);
 	}
 
+	/**
+	 * Clear the cache removing all of the entries cached.
+	 */
 	public clear(): void {
 		this[PARENT].clear();
 	}
 
+	/**
+	 * Get all of the keys in the cache as an array. Can be used to iterate
+	 * over all of the values in the cache, but be sure to protect against
+	 * values being removed during iteration due to time-based expiration if
+	 * used.
+	 *
+	 * @returns
+	 *   snapshot of keys
+	 */
 	public keys(): K[] {
 		return this[PARENT].keys();
 	}
 
+	/**
+	 * Request clean up of the cache by removing expired entries and
+	 * old data. Clean up is done automatically a short time after sets and
+	 * deletes, but if your cache uses time-based expiration and has very
+	 * sporadic updates it might be a good idea to call `cleanUp()` at times.
+	 *
+	 * A good starting point would be to call `cleanUp()` in a `setInterval`
+	 * with a delay of at least a few minutes.
+	 */
 	public cleanUp(): void {
 		this[PARENT].cleanUp();
 	}
 
+	/**
+	 * Get metrics for this cache. Returns an object with the keys `hits`,
+	 * `misses` and `hitRate`. For caches that do not have metrics enabled
+	 * trying to access metrics will throw an error.
+	 *
+	 * @returns
+	 *   metrics
+	 */
 	public get metrics(): Metrics {
 		return this[PARENT].metrics;
 	}