doc: add documentation to all store helper functions

toddeTV · toddeTV · Aug 16, 2024 · Jul 14, 2024 · Jul 15, 2024 · Jul 15, 2024
commit fde38540af393a3590a64dc7acb10f85d5770421
diff --git a/src/composables/useRegisteredForSelectingModelStore.ts b/src/composables/useRegisteredForSelectingModelStore.ts
@@ -3,17 +3,34 @@ import type { Object3D } from 'three'
 import { reactive } from 'vue'
 
 export default defineStore('registeredForSelectingModelStore', () => {
-  // store only the `id` of the `Object3D` object for performance reasons
+  // Store only the `id` of the `Object3D` object for performance reasons
   const registered = reactive(new Set<number>())
 
+  /**
+   * Retrieves all registered Object3D IDs.
+   *
+   * @returns {number[]} - An array of registered Object3D IDs.
+   */
   function getRegisteredAll(): number[] {
     return Array.from(registered)
   }
 
+  /**
+   * Checks if the given Object3D instance is registered.
+   *
+   * @param {Object3D} obj - The Object3D instance to check.
+   * @returns {boolean} - Returns true if the Object3D instance is registered, otherwise false.
+   */
   function isRegistered(obj: Object3D): boolean {
     return registered.has(getObject3DId(obj))
   }
 
+  /**
+   * Registers the given Object3D instance.
+   *
+   * @param {Object3D} obj - The Object3D instance to register.
+   * @returns {boolean} - Returns true if the Object3D instance was successfully registered, otherwise false.
+   */
   function register(obj: Object3D): boolean {
     if (isRegistered(obj)) {
       return false
@@ -22,6 +39,12 @@ export default defineStore('registeredForSelectingModelStore', () => {
     return true
   }
 
+  /**
+   * Unregisters the given Object3D instance.
+   *
+   * @param {Object3D} obj - The Object3D instance to unregister.
+   * @returns {boolean} - Returns true if the Object3D instance was successfully unregistered, otherwise false.
+   */
   function unregister(obj: Object3D): boolean {
     if (!isRegistered(obj)) {
       return false
@@ -30,10 +53,19 @@ export default defineStore('registeredForSelectingModelStore', () => {
     return true
   }
 
+  /**
+   * Unregisters all Object3D instances.
+   */
   function unregisterAll() {
     registered.clear()
   }
 
+  /**
+   * Retrieves the ID of the given Object3D instance.
+   *
+   * @param {Object3D} obj - The Object3D instance to get the ID from.
+   * @returns {number} - The ID of the Object3D instance.
+   */
   function getObject3DId(obj: Object3D): number {
     return obj.id
   }

diff --git a/src/composables/useSelectedModelsStore.ts b/src/composables/useSelectedModelsStore.ts
@@ -6,25 +6,49 @@ import useRegisteredForSelectingModelStore from '@/composables/useRegisteredForS
 export default defineStore('selectedModelsStore', () => {
   const registeredForSelectingModelStore = useRegisteredForSelectingModelStore()
 
-  // Store the real `Object3D` object for faster access without converting e.g. a stored `id: number` first
-  // back to the real object. Also, we would need the scene's `useContext()` to get the real object
-  // via `<context>.getObjectById(id: number): Object3D | undefined`.
-  // We use `reactive` instead of `ref` bc it is deeper reactive into the object. But bc a reactive can't be
-  // set again, we must wrap the one object we want to store in a data structure like an Array, Set, ...
+  /*
+  Store the real `Object3D` object for faster access without converting e.g. a stored `id: number` first
+  back to the real object. Also, we would need the scene's `useTresContext()` to get the real object
+  via `<context>.getObjectById(id: number): Object3D | undefined`.
+  We use `reactive` instead of `ref` bc it is deeper reactive into the object. But bc a reactive can't be
+  set again, we must wrap the one object we want to store in a data structure like an Array, Set, ...
+  */
   const selected = reactive(new Set<Object3D>())
 
+  /**
+   * Function to get the selected Object3D instance.
+   *
+   * @returns {Object3D | undefined} - The selected Object3D instance or undefined if none is selected.
+   */
   function getSelected(): Object3D | undefined {
     return Array.from(selected)[0]
   }
 
+  /**
+   * Checks if the given Object3D instance is the currently selected one.
+   *
+   * @param {Object3D} obj - The Object3D instance to check.
+   * @returns {boolean} - Returns true if the given Object3D instance is selected, otherwise false.
+   */
   function isSelected(obj: Object3D): boolean {
     return getSelected()?.id === obj.id
   }
 
+  /**
+   * Checks if there is any Object3D instance selected.
+   *
+   * @returns {boolean} - Returns true if there is at least one Object3D instance selected, otherwise false.
+   */
   function hasSelected(): boolean {
     return selected.size > 0
   }
 
+  /**
+   * Selects the given Object3D instance if it is registered.
+   *
+   * @param {Object3D} obj - The Object3D instance to select.
+   * @returns {boolean} - Returns true if the object was successfully selected, otherwise false.
+   */
   function select(obj: Object3D): boolean {
     if (!registeredForSelectingModelStore.isRegistered(obj)) {
       return false
@@ -34,6 +58,12 @@ export default defineStore('selectedModelsStore', () => {
     return true
   }
 
+  /**
+   * Unselects the given Object3D instance if it is currently selected.
+   *
+   * @param {Object3D} obj - The Object3D instance to unselect.
+   * @returns {boolean} - Returns true if the object was successfully unselected, otherwise false.
+   */
   function unselect(obj: Object3D): boolean {
     if (!isSelected(obj)) {
       return false
@@ -42,11 +72,24 @@ export default defineStore('selectedModelsStore', () => {
     return true
   }
 
+  /**
+   * Unselects all currently selected Object3D instances.
+   *
+   * @returns {boolean} - Returns true if all objects were successfully unselected.
+   */
   function unselectAll(): boolean {
     selected.clear()
     return true
   }
 
+  /**
+   * Toggles the selection state of the given Object3D instance.
+   * If the object is currently selected, it will be unselected.
+   * If the object is not currently selected, it will be selected.
+   *
+   * @param {Object3D} obj - The Object3D instance to toggle.
+   * @returns {boolean} - Returns true if the object's selection state was successfully toggled.
+   */
   function toggle(obj: Object3D): boolean {
     if (isSelected(obj)) {
       return unselect(obj)