Merge 6922416 into 6b934fa

src/imageCache.js

@@ -15,6 +15,11 @@ const imageCacheDict = {};
 // Array of cachedImage objects
 export const cachedImages = [];
 
+/** Sets the maximum size of cache and purges cache contents if necessary.
+ *
+ * @param {number} numBytes The maximun size that the cache should occupy.
+ * @returns {void}
+ */
 export function setMaximumSizeBytes (numBytes) {
   if (numBytes === undefined) {
     throw new Error('setMaximumSizeBytes: parameter numBytes must not be undefined');
@@ -30,6 +35,10 @@ export function setMaximumSizeBytes (numBytes) {
   purgeCacheIfNecessary();
 }
 
+/**
+ * Purges the cache if size exceeds maximum
+ * @returns {void}
+ */
 function purgeCacheIfNecessary () {
   // If max cache size has not been exceeded, do nothing
   if (cacheSizeInBytes <= maximumSizeInBytes) {
@@ -65,6 +74,12 @@ function purgeCacheIfNecessary () {
   triggerEvent(events, EVENTS.IMAGE_CACHE_FULL, cacheInfo);
 }
 
+/**
+ * Puts a new image loader into the cache
+ *
+ * @param {string} imageId ImageId of the image loader
+ * @param {Object} imageLoadObject The object that is loading or loaded the image
+ */
 export function putImageLoadObject (imageId, imageLoadObject) {
   if (imageId === undefined) {
     throw new Error('putImageLoadObject: imageId must not be undefined');
@@ -128,6 +143,11 @@ export function putImageLoadObject (imageId, imageLoadObject) {
   });
 }
 
+/**
+ * Retuns the object that is loading a given imageId
+ *
+ * @param {string} imageId
+ */
 export function getImageLoadObject (imageId) {
   if (imageId === undefined) {
     throw new Error('getImageLoadObject: imageId must not be undefined');
@@ -144,6 +164,11 @@ export function getImageLoadObject (imageId) {
   return cachedImage.imageLoadObject;
 }
 
+/**
+ * Removes the image loader associated with a given Id from the cache
+ *
+ * @param {string} imageId
+ */
 export function removeImageLoadObject (imageId) {
   if (imageId === undefined) {
     throw new Error('removeImageLoadObject: imageId must not be undefined');
@@ -168,6 +193,16 @@ export function removeImageLoadObject (imageId) {
   delete imageCacheDict[imageId];
 }
 
+/**
+ * @typedef {Object} CacheInformation
+ * @property {number} maximumSizeInBytes  The maximum size of the cache in bytes
+ * @property {number} cacheSizeInBytes Currently occupied space in the cache in bytes
+ * @property {number} numberOfImagesCached Number of ImageLoaders in the cache
+ */
+
+/**
+ * Gets the current state of the cache
+ */
 export function getCacheInfo () {
   return {
     maximumSizeInBytes,
@@ -178,6 +213,11 @@ export function getCacheInfo () {
 
 // This method should only be called by `removeImageLoadObject` because it's
 // The one that knows how to deal with shared cache keys and cache size.
+/**
+ * INTERNAL: Removes and ImageLoader from the cache
+ *
+ * @param {Object} imageLoadObject
+ */
 function decache (imageLoadObject) {
   imageLoadObject.promise.then(
     function () {
@@ -193,6 +233,9 @@ function decache (imageLoadObject) {
   );
 }
 
+/**
+ * Removes all images from cache
+ */
 export function purgeCache () {
   while (cachedImages.length > 0) {
     const removedCachedImage = cachedImages[0];
@@ -201,6 +244,12 @@ export function purgeCache () {
   }
 }
 
+/**
+ * Updates the space than an image is using in the cache
+ *
+ * @param {string} imageId
+ * @param {number} newCacheSize
+ */
 export function changeImageIdCacheSize (imageId, newCacheSize) {
   const cacheEntry = imageCacheDict[imageId];