chore: documentation for project composable

packages/client/hmi-client/src/composables/project.ts

@@ -18,8 +18,13 @@ const allProjects = shallowRef<IProject[] | null>(null);
 const activeProjectId = computed<string>(() => activeProject.value?.id ?? '');
 
 export function useProjects() {
-	// refresh the current activeProject if `projectId` is not defined
-	// otherwise get and set the current project to the one specified by `projectId`
+	/**
+	 * Refreshes the active project from backend if `projectId` is not defined.
+	 * Otherwise get and set the active project to the one specified by `projectId`.
+	 *
+	 * @param {string} projectId Id of the project to set as the active project.
+	 * @returns {Promise<IProject | null>} Active project.
+	 */
 	async function get(projectId?: IProject['id']): Promise<IProject | null> {
 		if (projectId) {
 			activeProject.value = await ProjectService.get(projectId, true);
@@ -29,11 +34,24 @@ export function useProjects() {
 		return activeProject.value;
 	}
 
+	/**
+	 * Refreshes the list of all projects from backend.
+	 * @returns {Promise<IProject[]>} List of all projects.
+	 */
 	async function getAll(): Promise<IProject[]> {
 		allProjects.value = (await ProjectService.getAll()) as unknown as IProject[];
 		return allProjects.value;
 	}
 
+	/**
+	 * If `projectId` is defined, add an asset to that project.
+	 * Otherwise, add an asset to the active project and refresh it.
+	 *
+	 * @param {string} assetType Type of asset to be added, e.g., 'documents'.
+	 * @param {string} assetId Id of the asset to be added. This will be the internal id of some asset stored in one of the data service collections.
+	 * @param {string} [projectId] Id of the project to add the asset to.
+	 * @returns {Promise<string|null>} Id of the added asset, if successful. Null, otherwise.
+	 */
 	async function addAsset(assetType: string, assetId: string, projectId?: string) {
 		const newAssetId = await ProjectService.addAsset(
 			projectId ?? activeProjectId.value,
@@ -48,6 +66,15 @@ export function useProjects() {
 		return newAssetId;
 	}
 
+	/**
+	 * If `projectId` is defined, delete an asset from that project.
+	 * Otherwise, delete an asset from the active project and refresh it.
+	 *
+	 * @param {string} assetType Type of asset to be deleted, e.g., 'documents'.
+	 * @param {string} assetId Id of the asset to be deleted. This will be the internal id of some asset stored in one of the data service collections.
+	 * @param {string} [projectId] Id of the project to delete the asset from.
+	 * @returns {Promise<boolean>} True if the asset was successfuly deleted. False, otherwise.
+	 */
 	async function deleteAsset(assetType: AssetType, assetId: string, projectId?: string) {
 		const deleted = await ProjectService.deleteAsset(
 			projectId ?? activeProjectId.value,
@@ -62,6 +89,14 @@ export function useProjects() {
 		return deleted;
 	}
 
+	/**
+	 * Create a new project and refresh the list of all projects.
+	 *
+	 * @param {string} name Name of the project.
+	 * @param {string} description Short description.
+	 * @param {string} username Username of the owner of the project.
+	 * @returns {Promise<Project|null>} The created project, or null if none returned by the API.
+	 */
 	async function create(name: string, description: string, username: string) {
 		const created = await ProjectService.create(name, description, username);
 		setTimeout(async () => {
@@ -70,14 +105,28 @@ export function useProjects() {
 		return created;
 	}
 
+	/**
+	 * Update a project. If updated project is the active project, refresh it.
+	 *
+	 * @param {Iproject} project Project to update.
+	 * @returns {Promise<string>} Id of the updated project.
+	 */
 	async function update(project: IProject) {
 		const updated = await ProjectService.update(project);
-		setTimeout(async () => {
-			activeProject.value = await ProjectService.get(project.id, true);
-		}, 1000);
+		if (project.id === activeProjectId.value) {
+			setTimeout(async () => {
+				activeProject.value = await ProjectService.get(project.id, true);
+			}, 1000);
+		}
 		return updated;
 	}
 
+	/**
+	 * Remove a project and refresh the list of all projects. Sets the active project to null.
+	 *
+	 * @param {string} projectId Id of the project to remove.
+	 * @returns {Promise<string>} Id of the project to remove.
+	 */
 	async function remove(projectId: IProject['id']) {
 		const removed = await ProjectService.remove(projectId);
 		setTimeout(async () => {
@@ -91,6 +140,12 @@ export function useProjects() {
 		return removed;
 	}
 
+	/**
+	 * Get projects publication assets for a given project per id.
+	 *
+	 * @param {string} projectId Project id to get assets for.
+	 * @return {Promise<DocumentAsset[]>} The documents assets for the project.
+	 */
 	async function getPublicationAssets(projectId: IProject['id']) {
 		return ProjectService.getPublicationAssets(projectId);
 	}