From 949f13b00aa6f4816b87bbf987bc855dcae6f0c4 Mon Sep 17 00:00:00 2001 From: Prozilla Date: Sun, 23 Jul 2023 12:45:27 +0200 Subject: [PATCH] Updated JSDoc comments for virtual drive --- src/features/virtual-drive/virtual-base.js | 13 ++- src/features/virtual-drive/virtual-file.js | 32 +++++++ src/features/virtual-drive/virtual-folder.js | 87 ++++++++++++++++++-- src/features/virtual-drive/virtual-root.js | 8 ++ 4 files changed, 131 insertions(+), 9 deletions(-) diff --git a/src/features/virtual-drive/virtual-base.js b/src/features/virtual-drive/virtual-base.js index ba7d76e..5939894 100644 --- a/src/features/virtual-drive/virtual-base.js +++ b/src/features/virtual-drive/virtual-base.js @@ -1,3 +1,5 @@ +// eslint-disable-next-line no-unused-vars +import { VirtualRoot } from "./virtual-root.js"; export class VirtualBase { /** @@ -13,12 +15,17 @@ export class VirtualBase { /** * @param {String} name + * @returns {VirtualBase} */ setName(name) { this.name = name; return this; } + /** + * @param {String} alias + * @returns {ThisType} + */ setAlias(alias) { this.alias = alias; this.getRoot().addShortcut(alias, this); @@ -26,7 +33,8 @@ export class VirtualBase { } /** - * @param {VirtualBase} parent + * @param {VirtualBase} parent + * @returns {VirtualBase} */ setParent(parent) { this.parent = parent; @@ -49,6 +57,9 @@ export class VirtualBase { return this.parent?.path + "/" + this.id; } + /** + * @returns {VirtualRoot} + */ getRoot() { const root = this.root ?? this.parent.getRoot(); diff --git a/src/features/virtual-drive/virtual-file.js b/src/features/virtual-drive/virtual-file.js index 2debf2a..252993b 100644 --- a/src/features/virtual-drive/virtual-file.js +++ b/src/features/virtual-drive/virtual-file.js @@ -1,13 +1,45 @@ import { VirtualBase } from "./virtual-base.js"; +/** + * A virtual file that can be stored inside a folder + */ export class VirtualFile extends VirtualBase { + /** + * @param {String} name + * @param {String=} extension + */ constructor(name, extension) { super(name); this.extension = extension; } + /** + * @param {String} alias + * @returns {VirtualFile} + */ + setAlias(alias) { + super.setAlias(alias); + } + + /** + * Sets the source of this file and removes the content + * @param {String} source + * @returns {VirtualFile} + */ setSource(source) { this.source = source; + this.content = null; + return this; + } + + /** + * Sets the content of this file and removes the source + * @param {String|*} content + * @returns {VirtualFile} + */ + setContent(content) { + this.content = content; + this.source = null; return this; } diff --git a/src/features/virtual-drive/virtual-folder.js b/src/features/virtual-drive/virtual-folder.js index 9035014..b37b958 100644 --- a/src/features/virtual-drive/virtual-folder.js +++ b/src/features/virtual-drive/virtual-folder.js @@ -2,6 +2,9 @@ import { removeFromArray } from "../utils/array.js"; import { VirtualBase } from "./virtual-base.js"; import { VirtualFile } from "./virtual-file.js"; +/** + * A virtual folder that can contains files and sub-folders + */ export class VirtualFolder extends VirtualBase { static TYPE = { GENERAL: 0, @@ -19,18 +22,39 @@ export class VirtualFolder extends VirtualBase { this.type = type ?? VirtualFolder.TYPE.GENERAL; } - // add(element) { - - // } + /** + * @param {String} alias + * @returns {VirtualFolder} + */ + setAlias(alias) { + super.setAlias(alias); + } + /** + * Returns true if this folder contains a file matching a name and extension + * @param {String} name + * @param {String} extension + * @returns {VirtualFile} + */ hasFile(name, extension) { return this.findFile(name, extension) !== null; } + /** + * Returns true if this folder contains a folder matching a name + * @param {String} name + * @returns {boolean} + */ hasFolder(name) { return this.findSubFolder(name) !== null; } + /** + * Finds and returns a file inside this folder matching a name and extension + * @param {String} name + * @param {String} extension + * @returns {VirtualFile} + */ findFile(name, extension) { let resultFile = null; @@ -43,6 +67,11 @@ export class VirtualFolder extends VirtualBase { return resultFile; } + /** + * Finds and returns a folder inside this folder matching a name + * @param {String} name + * @returns {VirtualFolder} + */ findSubFolder(name) { let resultFolder = null; @@ -56,9 +85,15 @@ export class VirtualFolder extends VirtualBase { } /** + * @callback createFileCallback + * @param {VirtualFile} newFile + */ + + /** + * Creates a file with a name and extension * @param {String} name * @param {String} extension - * @param {Function} callback + * @param {createFileCallback} callback * @returns {VirtualFolder} */ createFile(name, extension, callback) { @@ -70,8 +105,11 @@ export class VirtualFolder extends VirtualBase { } /** - * @param {Array} files - * @returns {VirtualFolder} + * Creates files based on an array of objects with file names and extensions + * @param {Object[]} files + * @param {String} Object[].name + * @param {String} Object[].extension + * @returns {VirtualFolder} */ createFiles(files) { files.forEach(({name, extension}) => { @@ -81,9 +119,15 @@ export class VirtualFolder extends VirtualBase { } /** + * @callback createFolderCallback + * @param {VirtualFolder} newFolder + */ + + /** + * Creates a folder with a name * @param {String} name * @returns {VirtualFolder} - * @param {Function} callback + * @param {createFolderCallback} callback */ createFolder(name, callback) { const newFolder = new VirtualFolder(name); @@ -94,7 +138,8 @@ export class VirtualFolder extends VirtualBase { } /** - * @param {Array} folders + * Creates folders based on an array of folder names + * @param {String[]} folders * @returns {VirtualFolder} */ createFolders(folders) { @@ -105,6 +150,8 @@ export class VirtualFolder extends VirtualBase { } /** + * Adds a file at a destination + * @deprecated * @param {String} destination */ addFile(destination) { @@ -127,6 +174,8 @@ export class VirtualFolder extends VirtualBase { } /** + * Adds a folder at a destination + * @deprecated * @param {String} destination */ addFolder(destination) { @@ -143,7 +192,13 @@ export class VirtualFolder extends VirtualBase { }) } + /** + * Removes a file or folder from this folder + * @param {VirtualFile|VirtualFolder} child + */ remove(child) { + child.parent = null; + if (child instanceof VirtualFile) { removeFromArray(child, this.files); } else if (child instanceof VirtualFolder) { @@ -151,6 +206,11 @@ export class VirtualFolder extends VirtualBase { } } + /** + * Returns the file or folder at a relative path or null if it doesn't exist + * @param {String} relativePath + * @returns {VirtualFile|VirtualFolder|null} + */ navigate(relativePath) { const segments = relativePath.split("/"); let currentDirectory = this; @@ -192,4 +252,15 @@ export class VirtualFolder extends VirtualBase { return null; } } + + /** + * Deletes this folder and all its files and sub-folders recursively + */ + delete() { + super.delete(); + + this.files.concat(this.subFolders).forEach((item) => { + item.delete(); + }); + } } \ No newline at end of file diff --git a/src/features/virtual-drive/virtual-root.js b/src/features/virtual-drive/virtual-root.js index 75abc74..c2f8dbe 100644 --- a/src/features/virtual-drive/virtual-root.js +++ b/src/features/virtual-drive/virtual-root.js @@ -1,3 +1,5 @@ +// eslint-disable-next-line no-unused-vars +import { VirtualFile } from "./virtual-file.js"; import { VirtualFolder } from "./virtual-folder.js"; /** @@ -10,6 +12,12 @@ export class VirtualRoot extends VirtualFolder { this.shortcuts = {}; } + /** + * Adds a shortcut to a file or folder + * @param {String} name + * @param {VirtualFile|VirtualFolder} destination + * @returns {VirtualRoot} + */ addShortcut(name, destination) { this.shortcuts[name] = destination; return this;