Make standalone function names clearer

apps/smart-forms-app/src/features/prepopulate/hooks/usePopulate.tsx

@@ -22,7 +22,7 @@ import { populateQuestionnaire } from '../utils/populate.ts';
 import CloseSnackbar from '../../../components/Snackbar/CloseSnackbar.tsx';
 import { useSnackbar } from 'notistack';
 import {
-  setPopulatedResponse,
+  setUpdatableResponse,
   useSourceQuestionnaire,
   useSourceResponse,
   useUpdatableResponse
@@ -74,7 +74,7 @@ function usePopulate(spinnerIsLoading: boolean, onStopSpinner: () => void): void
     (params: PopulateFormParams) => {
       const { populated, hasWarnings } = params;
 
-      setPopulatedResponse(populated);
+      setUpdatableResponse(populated);
       onStopSpinner();
       if (hasWarnings) {
         enqueueSnackbar(

apps/smart-forms-app/src/features/renderer/components/RendererDebugFooter/RendererDebugFooter.tsx

@@ -21,7 +21,7 @@ import DebugResponse from './DebugResponse.tsx';
 import type { QuestionnaireResponseItem } from 'fhir/r4';
 import RendererDebugBar from './RendererDebugBar.tsx';
 import {
-  setEmptyResponse,
+  setUpdatableResponseAsEmpty,
   useSourceQuestionnaire,
   useUpdatableResponse
 } from '@aehrc/smart-forms-renderer';
@@ -47,7 +47,7 @@ function RendererDebugFooter() {
       updatableResponse.item.length
     ).fill(clearTopLevelQRItem);
 
-    setEmptyResponse({
+    setUpdatableResponseAsEmpty({
       ...updatableResponse,
       item: clearTopLevelQRItems
     });

apps/smart-forms-app/src/features/renderer/components/RendererEmbeddedSpeedDial.tsx

@@ -33,7 +33,7 @@ import GradingIcon from '@mui/icons-material/Grading';
 import ReadMoreIcon from '@mui/icons-material/ReadMore';
 import {
   removeHiddenAnswersFromResponse,
-  setSavedResponse,
+  setUpdatableResponseAsSaved,
   useSourceQuestionnaire,
   useUpdatableResponse
 } from '@aehrc/smart-forms-renderer';
@@ -80,7 +80,7 @@ function RendererEmbeddedSpeedDial(props: RendererEmbeddedSpeedDialProps) {
     responseToSave.status = 'in-progress';
     saveQuestionnaireResponse(smartClient, patient, user, sourceQuestionnaire, responseToSave)
       .then((savedResponse) => {
-        setSavedResponse(savedResponse);
+        setUpdatableResponseAsSaved(savedResponse);
         enqueueSnackbar('Response saved as draft', {
           variant: 'success',
           action: (

apps/smart-forms-app/src/features/renderer/components/RendererNav/BlockerUnsavedFormDialog.tsx

@@ -32,7 +32,7 @@ import useConfigStore from '../../../../stores/useConfigStore.ts';
 import { LoadingButton } from '@mui/lab';
 import {
   removeHiddenAnswersFromResponse,
-  setSavedResponse,
+  setUpdatableResponseAsSaved,
   useSourceQuestionnaire,
   useUpdatableResponse
 } from '@aehrc/smart-forms-renderer';
@@ -87,7 +87,7 @@ function BlockerUnsavedFormDialog(props: Props) {
     responseToSave.status = 'in-progress';
     saveQuestionnaireResponse(smartClient, patient, user, sourceQuestionnaire, responseToSave)
       .then((savedResponse) => {
-        setSavedResponse(savedResponse);
+        setUpdatableResponseAsSaved(savedResponse);
         setIsSaving(false);
         closeDialog();
         blocker.proceed?.();

apps/smart-forms-app/src/features/renderer/components/RendererNav/SaveAsDraft/RendererSaveAsDraft.tsx

@@ -28,7 +28,7 @@ import { IconButton, Tooltip } from '@mui/material';
 import ReadMoreIcon from '@mui/icons-material/ReadMore';
 import {
   removeHiddenAnswersFromResponse,
-  setSavedResponse,
+  setUpdatableResponseAsSaved,
   useFormHasChanges,
   useSourceQuestionnaire,
   useUpdatableResponse
@@ -73,7 +73,7 @@ function RendererSaveAsDraft() {
     responseToSave.status = 'in-progress';
     saveQuestionnaireResponse(smartClient, patient, user, sourceQuestionnaire, responseToSave)
       .then((savedResponse) => {
-        setSavedResponse(savedResponse);
+        setUpdatableResponseAsSaved(savedResponse);
         enqueueSnackbar('Response saved as draft', {
           variant: 'success',
           action: (

apps/smart-forms-app/src/features/renderer/components/RendererNav/SaveAsFinal/RendererSaveAsFinalDialog.tsx

@@ -32,7 +32,7 @@ import useConfigStore from '../../../../../stores/useConfigStore.ts';
 import { LoadingButton } from '@mui/lab';
 import {
   removeHiddenAnswersFromResponse,
-  setSavedResponse,
+  setUpdatableResponseAsSaved,
   useSourceQuestionnaire,
   useUpdatableResponse
 } from '@aehrc/smart-forms-renderer';
@@ -77,7 +77,7 @@ function RendererSaveAsFinalDialog(props: RendererSaveAsFinalDialogProps) {
     responseToSave.status = 'completed';
     saveQuestionnaireResponse(smartClient, patient, user, sourceQuestionnaire, responseToSave)
       .then((savedResponse) => {
-        setSavedResponse(savedResponse);
+        setUpdatableResponseAsSaved(savedResponse);
         enqueueSnackbar('Response saved as final', { variant: 'success' });
 
         // Wait until renderer.hasChanges is set to false before navigating away

apps/smart-forms-app/src/features/viewer/ViewerNav/SaveAsFinal/ViewerSaveAsFinalDialog.tsx

@@ -31,7 +31,7 @@ import {
 import useConfigStore from '../../../../stores/useConfigStore.ts';
 import { LoadingButton } from '@mui/lab';
 import {
-  setSavedResponse,
+  setUpdatableResponseAsSaved,
   useSourceQuestionnaire,
   useUpdatableResponse
 } from '@aehrc/smart-forms-renderer';
@@ -75,7 +75,7 @@ function ViewerSaveAsFinalDialog(props: ViewerSaveAsFinalDialogProps) {
     saveQuestionnaireResponse(smartClient, patient, user, sourceQuestionnaire, responseToSave)
       .then((savedResponse) => {
         setIsSaving(false);
-        setSavedResponse(savedResponse);
+        setUpdatableResponseAsSaved(savedResponse);
         handleClose();
         enqueueSnackbar('Response saved as final', { variant: 'success' });
         navigate(launchQuestionnaireExists ? '/dashboard/existing' : '/dashboard/responses');

packages/smart-forms-renderer/src/index.ts

@@ -7,29 +7,70 @@ import { removeHiddenAnswers } from './utils/removeHidden';
 export * from './components';
 export * from './hooks';
 
+/**
+ * Get the initial Questionnaire.
+ *
+ * @author Sean Fong
+ */
 export function useSourceQuestionnaire(): Questionnaire {
   return useQuestionnaireStore.getState().sourceQuestionnaire;
 }
 
+/**
+ * Get the initial QuestionnaireResponse.
+ * An empty QuestionnaireResponse is returned if no initial QuestionnaireResponse is provided when building the form.
+ *
+ * @author Sean Fong
+ */
 export function useSourceResponse(): QuestionnaireResponse {
   return useQuestionnaireResponseStore.getState().sourceResponse;
 }
 
+/**
+ * Get the filled QuestionnaireResponse.
+ * If no changes have been made to the form, the initial QuestionnaireResponse is returned.
+ *
+ * @author Sean Fong
+ */
 export function useUpdatableResponse(): QuestionnaireResponse {
   return useQuestionnaireResponseStore.getState().updatableResponse;
 }
+
+/**
+ * Get the boolean value of whether any changes have been made to the form.
+ *
+ * @author Sean Fong
+ */
 export function useFormHasChanges(): boolean {
   return useQuestionnaireResponseStore.getState().hasChanges;
 }
 
+/**
+ * Get the boolean value of whether enableWhen (and enableWhenExpression) is activated.
+ *
+ * @author Sean Fong
+ */
 export function useEnableWhenActivated(): boolean {
   return useQuestionnaireStore.getState().enableWhenIsActivated;
 }
 
+/**
+ * Set the initial Questionnaire.
+ * In most cases, <pre>buildForm()</pre> should be used instead.
+ *
+ * @author Sean Fong
+ */
 export async function setSourceQuestionnaire(questionnaire: Questionnaire): Promise<void> {
   await useQuestionnaireStore.getState().buildSourceQuestionnaire(questionnaire);
 }
 
+/**
+ * Build the form with an initial Questionnaire and an optional filled QuestionnaireResponse.
+ * If a QuestionnaireResponse is not provided, an empty QuestionnaireResponse is set as the initial QuestionnaireResponse.
+ * In most cases, <pre>buildForm()</pre> is sufficient. Other fine-grained functions are provided for more control.
+ *
+ * @author Sean Fong
+ */
 export async function buildForm(
   questionnaire: Questionnaire,
   questionnaireResponse?: QuestionnaireResponse
@@ -47,30 +88,63 @@ export async function buildForm(
   useQuestionnaireStore.getState().updatePopulatedProperties(questionnaireResponse);
 }
 
+/**
+ * Destroy the form to clean up the store.
+ *
+ * @author Sean Fong
+ */
 export function destroyForm(): void {
   useQuestionnaireStore.getState().destroySourceQuestionnaire();
   useQuestionnaireResponseStore.getState().destroySourceResponse();
 }
 
+/**
+ * Toggle activation of enableWhen (and enableWhenExpression).
+ *
+ * @author Sean Fong
+ */
 export function setEnableWhenActivation(isActivated: boolean): void {
   useQuestionnaireStore.getState().toggleEnableWhenActivation(isActivated);
 }
 
-export function setPopulatedResponse(populatedResponse: QuestionnaireResponse): void {
+/**
+ * Set the filled QuestionnaireResponse.
+ * In most cases, <pre>buildForm()</pre> should be used instead.
+ *
+ * @author Sean Fong
+ */
+export function setUpdatableResponse(populatedResponse: QuestionnaireResponse): void {
   const updatedResponse = useQuestionnaireStore
     .getState()
     .updatePopulatedProperties(populatedResponse);
   useQuestionnaireResponseStore.getState().populateResponse(updatedResponse);
 }
 
-export function setEmptyResponse(emptyResponse: QuestionnaireResponse): void {
+/**
+ * Set the filled QuestionnaireResponse to be empty.
+ * This is used to quickly clear the form.
+ *
+ * @author Sean Fong
+ */
+export function setUpdatableResponseAsEmpty(emptyResponse: QuestionnaireResponse): void {
   return useQuestionnaireResponseStore.getState().clearResponse(emptyResponse);
 }
 
-export function setSavedResponse(savedResponse: QuestionnaireResponse): void {
+/**
+ * Save the filled QuestionnaireResponse to be the initial QuestionnaireResponse and reset the <pre>hasChanges</pre> flag.
+ *
+ * @author Sean Fong
+ */
+export function setUpdatableResponseAsSaved(savedResponse: QuestionnaireResponse): void {
   return useQuestionnaireResponseStore.getState().saveResponse(savedResponse);
 }
 
+/**
+ * Remove all hidden answers from the filled QuestionnaireResponse.
+ * This takes into account the questionnaire-hidden extension, enableWhens and enableWhenExpressions.
+ *
+ * @author Sean Fong
+ */
 export function removeHiddenAnswersFromResponse(
   questionnaire: Questionnaire,
   questionnaireResponse: QuestionnaireResponse