Add docu for selectors

src/state/selectors/annotations.js

@@ -7,7 +7,11 @@ import { getCanvas, getVisibleCanvasIds } from './canvases';
 import { getConfig } from './config';
 import { getWindow } from './getters';
 
-/** */
+/**
+ * Returns the annotation object from the mirador slice.
+ * @param {object} state redux state
+ * @returns {object} Annotations from the state
+ */
 export const getAnnotations = state => miradorSlice(state).annotations;
 
 const getMotivation = createSelector(
@@ -60,6 +64,12 @@ const getAnnotationsOnSelectedCanvases = createSelector(
   },
 );
 
+/**
+ * Returns an array of present annotations given a canvasId.
+ * @param {object} state redux state
+ * @param {string} canvasId canvasId
+ * @returns {Array} An array of present annotations
+ */
 export const getPresentAnnotationsOnSelectedCanvases = createSelector(
   [
     getAnnotationsOnSelectedCanvases,
@@ -72,11 +82,11 @@ export const getPresentAnnotationsOnSelectedCanvases = createSelector(
 );
 
 /**
-* Return an array of annotation resources filtered by the given motivation for a particular canvas
-* @param {Array} annotations
-* @param {Array} motivations
-* @return {Array}
-*/
+ * Returns an array of annotation resources filtered by the given motivation for a particular canvas.
+ * @param {Array} annotations
+ * @param {Array} motivations
+ * @returns {Array}
+ */
 export const getAnnotationResourcesByMotivationForCanvas = createSelector(
   [
     getPresentAnnotationsCanvas,
@@ -91,11 +101,11 @@ export const getAnnotationResourcesByMotivationForCanvas = createSelector(
 );
 
 /**
-* Return an array of annotation resources filtered by the given motivation
-* @param {Array} annotations
-* @param {Array} motivations
-* @return {Array}
-*/
+ * Returns an array of annotation resources filtered by the given motivation.
+ * @param {Array} annotations
+ * @param {Array} motivations
+ * @returns {Array}
+ */
 export const getAnnotationResourcesByMotivation = createSelector(
   [
     getPresentAnnotationsOnSelectedCanvases,
@@ -110,11 +120,11 @@ export const getAnnotationResourcesByMotivation = createSelector(
 );
 
 /**
- * Return the selected annotations IDs of a given CanvasId
- * @param {Object} state
- * @param {String} windowId
+ * Returns the selected annotations IDs.
+ * @param {object} state
+ * @param {string} windowId
  * @param {Array} targetIds
- * @return {Array}
+ * @returns {Array}
  */
 export const getSelectedAnnotationId = createSelector(
   [
@@ -123,6 +133,11 @@ export const getSelectedAnnotationId = createSelector(
   ({ selectedAnnotationId }) => selectedAnnotationId,
 );
 
+/**
+ * Returns annotations on selected canvases.
+ * @param {object} state
+ * @returns {Array}
+ */
 export const getSelectedAnnotationsOnCanvases = createSelector(
   [
     getPresentAnnotationsOnSelectedCanvases,

src/state/selectors/auth.js

@@ -6,19 +6,38 @@ import { miradorSlice } from './utils';
 import { getConfig } from './config';
 import { getVisibleCanvases, selectInfoResponses } from './canvases';
 
+/**
+ * Returns the authentification profile from the configuration
+ * @param {object} state
+ * @returns {Array}
+ */
 export const getAuthProfiles = createSelector(
   [
     getConfig,
   ],
   ({ auth: { serviceProfiles = [] } = {} }) => serviceProfiles,
 );
 
-/** */
+/**
+ * Returns access tokens from the state
+ * @param {object} state
+ * @returns {object}
+ */
 export const getAccessTokens = state => miradorSlice(state).accessTokens || {};
 
-/** */
+/**
+ * Return the authentification data from the state
+ * @param {object} state
+ * @returns {object}
+ */
 export const getAuth = state => miradorSlice(state).auth || {};
 
+/**
+ * Returns current authentification services based on state and windowId
+ * @param {object} state
+ * @param {string} windowId
+ * @returns {Array}
+ */
 export const selectCurrentAuthServices = createSelector(
   [
     getVisibleCanvases,

src/state/selectors/canvases.js

@@ -7,7 +7,11 @@ import { getWindow } from './getters';
 import { getSequence } from './sequences';
 import { getWindowViewType } from './windows';
 
-/** */
+/**
+ * Returns the info response.
+ * @param {object} state
+ * @returns {object}
+ */
 export const selectInfoResponses = state => miradorSlice(state).infoResponses;
 
 export const getCanvases = createSelector(
@@ -16,13 +20,12 @@ export const getCanvases = createSelector(
 );
 
 /**
-* Return the canvas selected by an id
-* @param {object} state
-* @param {object} props
-* @param {string} props.manifestId
-* @param {string} props.windowId
-* @return {Object}
-*/
+ * Return the canvas selected by an id
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.canvasId
+ * @returns {object}
+ */
 export const getCanvas = createSelector(
   [
     getSequence,
@@ -35,6 +38,13 @@ export const getCanvas = createSelector(
   },
 );
 
+/**
+ * Returns the current canvas.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.windowId
+ * @returns {object|undefined}
+ */
 export const getCurrentCanvas = createSelector(
   [
     getSequence,
@@ -49,27 +59,39 @@ export const getCurrentCanvas = createSelector(
   },
 );
 
-/** */
+/**
+ * Returns the visible canvas ids.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.windowId
+ * @returns {Array}
+ */
 export const getVisibleCanvasIds = createSelector(
   [getWindow],
   window => (window && (window.visibleCanvases || (window.canvasId && [window.canvasId]))) || [],
 );
 
-/** */
+/**
+ * Returns the visible canvses.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.windowId
+ * @returns {Array}
+ */
 export const getVisibleCanvases = createSelector(
   [getVisibleCanvasIds, getCanvases],
   (canvasIds, canvases) => (canvases || []).filter(c => canvasIds.includes(c.id)),
 );
 
 /**
-* Return the current canvases grouped by how they'll appear in the viewer
-* For book view returns groups of 2, for single returns 1
-* @param {object} state
-* @param {object} props
-* @param {string} props.manifestId
-* @param {string} props.windowId
-* @return {Array}
-*/
+ * Return the current canvases grouped by how they'll appear in the viewer.
+ * For book view returns groups of 2, for single returns 1.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.manifestId
+ * @param {string} props.windowId
+ * @returns {Array}
+ */
 export const getCanvasGroupings = createSelector(
   [
     getCanvases,
@@ -83,14 +105,15 @@ export const getCanvasGroupings = createSelector(
 );
 
 /**
-* Return the current canvases selected in a window
-* For book view returns 2, for single returns 1
-* @param {object} state
-* @param {object} props
-* @param {string} props.manifestId
-* @param {string} props.windowId
-* @return {Array}
-*/
+ * Return the current canvases selected in a window.
+ * For book view returns 2, for single returns 1.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.manifestId
+ * @param {string} props.windowId
+ * @param {string} props.canvasId
+ * @returns {Array}
+ */
 export const getCanvasGrouping = createSelector(
   [
     getCanvasGroupings,
@@ -101,14 +124,14 @@ export const getCanvasGrouping = createSelector(
 );
 
 /**
-* Return the next canvas(es) for a window
-* For book view returns 2, for single returns 1
-* @param {object} state
-* @param {object} props
-* @param {string} props.manifestId
-* @param {string} props.windowId
-* @return {Array}
-*/
+ * Return the next canvas(es) for a window.
+ * For book view returns 2, for single returns 1.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.manifestId
+ * @param {string} props.windowId
+ * @returns {Array}
+ */
 export const getNextCanvasGrouping = createSelector(
   [
     getCanvasGroupings,
@@ -126,14 +149,14 @@ export const getNextCanvasGrouping = createSelector(
 );
 
 /**
-* Return the previous canvas(es) for a window
-* For book view returns 2, for single returns 1
-* @param {object} state
-* @param {object} props
-* @param {string} props.manifestId
-* @param {string} props.windowId
-* @return {Array}
-*/
+ * Return the previous canvas(es) for a window.
+ * For book view returns 2, for single returns 1.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.manifestId
+ * @param {string} props.windowId
+ * @returns {Array}
+ */
 export const getPreviousCanvasGrouping = createSelector(
   [
     getCanvasGroupings,
@@ -152,10 +175,13 @@ export const getPreviousCanvasGrouping = createSelector(
 );
 
 /**
-* Return canvas label, or alternatively return the given index + 1 to be displayed
-* @param {object} canvas
-* @return {String|Integer}
-*/
+ * Return canvas label, or alternatively return the given index + 1 to be displayed.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.canvasId
+ * @param {string} props.manifestId
+ * @returns {string|number}
+ */
 export const getCanvasLabel = createSelector(
   [getCanvas],
   canvas => (canvas && (
@@ -166,15 +192,21 @@ export const getCanvasLabel = createSelector(
 );
 
 /**
-* Return canvas description
-* @param {object} canvas
-* @param {String}
-*/
+ * Return canvas description.
+ * @param {object} canvas
+ * @param {string} companionWindowId
+ */
 export const getCanvasDescription = createSelector(
   [getCanvas],
   canvas => canvas && canvas.getProperty('description'),
 );
 
+/**
+ * Return visible non tiled canvas resources.
+ * @param {object}
+ * @param {string} windowId
+ * @returns {Array}
+ */
 export const getVisibleCanvasNonTiledResources = createSelector(
   [
     getVisibleCanvases,
@@ -184,6 +216,12 @@ export const getVisibleCanvasNonTiledResources = createSelector(
     .filter(resource => resource.getServices().length < 1),
 );
 
+/**
+ * Returns visible canvas video resources.
+ * @param {object} state
+ * @param {string} windowId
+ * @return {Array}
+ */
 export const getVisibleCanvasVideoResources = createSelector(
   [
     getVisibleCanvases,
@@ -192,6 +230,12 @@ export const getVisibleCanvasVideoResources = createSelector(
     .map(canvas => new MiradorCanvas(canvas).videoResources)),
 );
 
+/**
+ * Returns visible canvas captions.
+ * @param {object} state
+ * @param {string} windowId
+ * @return {Array}
+ */
 export const getVisibleCanvasCaptions = createSelector(
   [
     getVisibleCanvases,
@@ -204,6 +248,12 @@ export const getVisibleCanvasCaptions = createSelector(
   })),
 );
 
+/**
+ * Returns visible canvas audio resources.
+ * @param {object} state
+ * @param {string} windowId
+ * @return {Array}
+ */
 export const getVisibleCanvasAudioResources = createSelector(
   [
     getVisibleCanvases,
@@ -212,6 +262,15 @@ export const getVisibleCanvasAudioResources = createSelector(
     .map(canvas => new MiradorCanvas(canvas).audioResources)),
 );
 
+/**
+ * Returns info response.
+ * @param {object} state
+ * @param {object} props
+ * @param {string} props.windowId
+ * @param {string} props.canvasId
+ * @param {string} props.infoId
+ * @returns {object|undefined}
+ */
 export const selectInfoResponse = createSelector(
   [
     (state, { infoId }) => infoId,