updated api docs

Author: Nursid

docs/api/apiaccess/fs/createFile.md

@@ -37,7 +37,89 @@ data:
 <CBBaseInfo/> 
 <CBParameters/>
 
-### Example 
+## Examples
+
+### Basic File Creation
+
+```js
+// Create a simple text file
+const result = await codebolt.fs.createFile(
+    'example.txt', 
+    'This is the content of the file.', 
+    '/home/user/documents'
+);
+console.log('File created:', result);
+```
+
+### Creating Files with Complex Content
+
+```js
+// Create a JavaScript file with code content
+const jsCodeContent = `
+// Sample JavaScript file with various code definitions
+class TestClass {
+    constructor(name) {
+        this.name = name;
+    }
+    
+    testMethod() {
+        return 'Hello from ' + this.name;
+    }
+    
+    static staticMethod() {
+        return 'Static method called';
+    }
+}
+
+function testFunction(param1, param2) {
+    return param1 + param2;
+}
+
+const arrowFunction = (x, y) => x * y;
+
+module.exports = { TestClass, testFunction, arrowFunction };
+`;
+
+const createResult = await codebolt.fs.createFile(
+    'test-code-definitions.js', 
+    jsCodeContent, 
+    '.'
+);
+console.log('JavaScript file created:', createResult);
+```
+
+### Error Handling
+
+```js
+try {
+    const result = await codebolt.fs.createFile(
+        'test-file.txt', 
+        'This is a test file created by CodeboltJS', 
+        '.'
+    );
+    
+    if (result.success) {
+        console.log('✅ File created successfully:', result.fileName);
+        console.log('Message:', result.message);
+    } else {
+        console.log('❌ File creation failed:', result.message);
+    }
+} catch (error) {
+    console.error('Error creating file:', error.message);
+}
+```
+
+### Creating Files in Current Directory
+
+```js
+// Create a file in the current working directory
+const result = await codebolt.fs.createFile(
+    'fs-test-file.txt', 
+    'This is a test file created by CodeboltJS FS test', 
+    '.'
+);
+console.log('File created in current directory:', result);
+```
 
 ```js
 // Let's assume you want to create a file named example.txt in the /home/user/documents directory with some content.

docs/api/apiaccess/fs/createFolder.md

@@ -24,7 +24,70 @@ data:
 <CBBaseInfo/> 
 <CBParameters/>
 
-### Example 
+## Examples
+
+### Basic Folder Creation
+
+```js
+// Create a folder in a specific directory
+const result = await codebolt.fs.createFolder('exampleFolder', '/home/user/documents');
+console.log('Folder created:', result);
+```
+
+### Create Folder in Current Directory
+
+```js
+// Create a folder in the current working directory
+const folderResult = await codebolt.fs.createFolder('test-folder', '.');
+console.log('✅ Folder created:', folderResult);
+```
+
+### Complete Workflow with File Operations
+
+```js
+// Create a project structure
+await codebolt.fs.createFolder('my-project', '.');
+await codebolt.fs.createFolder('src', './my-project');
+
+// Create files in the folders
+await codebolt.fs.createFile('index.js', 'console.log("Hello World");', './my-project/src');
+
+// List the created structure
+const projectFiles = await codebolt.fs.listFile('./my-project', true);
+console.log('Project structure:', projectFiles);
+```
+
+### Create Multiple Folders
+
+```js
+// Create multiple folders for different purposes
+const folders = ['assets', 'components', 'utils', 'config'];
+
+for (const folder of folders) {
+    try {
+        const result = await codebolt.fs.createFolder(folder, '.');
+        console.log(`✅ Created folder: ${folder}`, result);
+    } catch (error) {
+        console.error(`❌ Failed to create folder ${folder}:`, error.message);
+    }
+}
+```
+
+### Error Handling
+
+```js
+try {
+    const result = await codebolt.fs.createFolder('test-folder', '.');
+    
+    if (result.success) {
+        console.log('✅ Folder created successfully');
+    } else {
+        console.log('❌ Folder creation failed:', result.message);
+    }
+} catch (error) {
+    console.error('Error creating folder:', error.message);
+}
+```
 
 ```js
 // Let's assume you want to create a folder named "exampleFolder" in the /home/user/documents directory.

docs/api/apiaccess/fs/deleteFile.md

@@ -24,9 +24,20 @@ data:
 <CBBaseInfo/> 
 <CBParameters/>
 
-### Example 
+## Examples
+
+### Basic File Deletion
 
 ```js
-// Let's assume you want to delete a file named example.txt in the /home/user/documents directory.
+// Delete a file from a specific directory
+const result = await codebolt.fs.deleteFile('example.txt', '/home/user/documents');
+console.log('File deleted:', result);
+```
+
+### Delete File from Current Directory
 
-codebolt.fs.deleteFile('example.txt', '/home/user/documents');
+```js
+// Delete a file from the current working directory
+const deleteResult = await codebolt.fs.deleteFile('fs-test-file.txt', '.');
+console.log('✅ File deleted:', deleteResult);
+```

docs/api/apiaccess/fs/deleteFolder.md

@@ -24,9 +24,20 @@ data:
 <CBBaseInfo/> 
 <CBParameters/>
 
-### Example 
+## Examples
+
+### Basic Folder Deletion
 
 ```js
-// Let's assume you want to delete a folder named "exampleFolder" in the /home/user/documents directory.
+// Delete a folder from a specific directory
+const result = await codebolt.fs.deleteFolder('exampleFolder', '/home/user/documents');
+console.log('Folder deleted:', result);
+```
+
+### Delete Folder from Current Directory
 
-codebolt.fs.deleteFolder('exampleFolder', '/home/user/documents');
+```js
+// Delete a folder from the current working directory
+const deleteFolderResult = await codebolt.fs.deleteFolder('test-folder', '.');
+console.log('✅ Folder deleted:', deleteFolderResult);
+```

docs/api/apiaccess/fs/index.md

@@ -2,35 +2,106 @@
 cbapicategory:
   - name: createFile
     link: /docs/api/apiaccess/fs/createFile
-    description: 'Creates a new file with the specified name and content.'
+    description: 'Creates a new file with the specified name and content. Supports creating files with complex content including code definitions.'
   - name: createFolder
     link: /docs/api/apiaccess/fs/createFolder
-    description: 'Creates a new folder at the specified location.'
+    description: 'Creates a new folder at the specified location. Useful for organizing project structures and temporary workspaces.'
   - name: readFile
     link: /docs/api/apiaccess/fs/readFile
-    description: 'Reads the contents of a file and returns it as a string.'
+    description: 'Reads the contents of a file and returns it as a string. Works with various file types including text, code, and configuration files.'
   - name: updateFile
     link: /docs/api/apiaccess/fs/updateFile
-    description: 'Updates an existing file with new content.'
+    description: 'Updates an existing file with new content. Requires separate filename and path parameters.'
+  - name: writeToFile
+    link: /docs/api/apiaccess/fs/writeToFile
+    description: 'Creates or updates a file and writes data to it. Uses a single relative path parameter and overwrites existing content.'
   - name: deleteFile
     link: /docs/api/apiaccess/fs/deleteFile
-    description: 'Deletes a specified file from the filesystem.'
+    description: 'Deletes a specified file from the filesystem. Includes proper error handling and cleanup workflows.'
   - name: deleteFolder
     link: /docs/api/apiaccess/fs/deleteFolder
-    description: 'Deletes a specified folder and its contents.'
+    description: 'Deletes a specified folder and its contents. Requires the folder to be empty before deletion.'
   - name: listFile
     link: /docs/api/apiaccess/fs/listFile
-    description: 'Lists all files in the specified directory.'
+    description: 'Lists all files in the specified directory. Supports recursive listing and enhanced file information modes.'
   - name: listCodeDefinitionNames
     link: /docs/api/apiaccess/fs/listCodeDefinitionNames
-    description: 'Lists all code definition names within a project.'
+    description: 'Extracts and lists all code definition names (functions, classes, methods) from source files within a project.'
   - name: searchFiles
     link: /docs/api/apiaccess/fs/searchFiles
-    description: 'Searches for files matching a specific pattern or criteria.'
-  - name: writeToFile
-    link: /docs/api/apiaccess/fs/writeToFile 
-    description: 'Creates or updates a file and writes data to it.'
+    description: 'Searches for files matching a regex pattern within file contents. Supports advanced regex patterns and file type filtering.'
 ---
 
 # fs
-<CBAPICategory />
+
+The `fs` module provides comprehensive file system operations for CodeboltJS. It includes methods for creating, reading, updating, and deleting files and folders, as well as advanced features like code definition extraction and content searching.
+
+<CBAPICategory />
+
+## Key Features
+
+### File Operations
+- **File Creation**: Create files with simple or complex content, including code definitions
+- **File Reading**: Read various file types (text, code, configuration files)
+- **File Updates**: Two methods available - `updateFile` (separate name/path) and `writeToFile` (single path)
+- **File Deletion**: Safe deletion with proper error handling and cleanup workflows
+
+### Folder Operations
+- **Folder Creation**: Create single folders or complex directory structures
+- **Folder Deletion**: Remove folders with proper cleanup procedures
+- **Directory Listing**: List files with options for recursive scanning and enhanced information
+
+### Advanced Features
+- **Code Analysis**: Extract function names, class names, and other code definitions from source files
+- **Content Search**: Search within file contents using regex patterns with file type filtering
+- **Batch Operations**: Perform operations on multiple files or folders efficiently
+
+## Common Workflows
+
+### Complete File Lifecycle
+```js
+// Create → Read → Update → Delete
+await codebolt.fs.createFile('example.txt', 'Initial content', '.');
+const content = await codebolt.fs.readFile('./example.txt');
+await codebolt.fs.updateFile('example.txt', '.', 'Updated content');
+await codebolt.fs.deleteFile('example.txt', '.');
+```
+
+### Project Structure Creation
+```js
+// Create organized project structure
+await codebolt.fs.createFolder('my-project', '.');
+await codebolt.fs.createFolder('src', './my-project');
+await codebolt.fs.createFolder('tests', './my-project');
+await codebolt.fs.createFile('index.js', 'console.log("Hello");', './my-project/src');
+```
+
+### Code Analysis Workflow
+```js
+// Create code file and extract definitions
+const jsCode = `
+class MyClass {
+    method() { return 'test'; }
+}
+function myFunction() { return 'hello'; }
+`;
+await codebolt.fs.createFile('code.js', jsCode, '.');
+const definitions = await codebolt.fs.listCodeDefinitionNames('.');
+```
+
+## Error Handling
+
+All fs methods return promises and should be used with proper error handling:
+
+```js
+try {
+    const result = await codebolt.fs.createFile('test.txt', 'content', '.');
+    if (result.success) {
+        console.log('✅ Operation successful');
+    } else {
+        console.log('❌ Operation failed:', result.message);
+    }
+} catch (error) {
+    console.error('Error:', error.message);
+}
+```

docs/api/apiaccess/fs/listCodeDefinitionNames.md

@@ -1,7 +1,7 @@
 ---
 name: listCodeDefinitionNames
 cbbaseinfo:
-  description: 'Lists all code definition names in a given path.'
+  description: 'Lists all code definition names in a given path. Extracts function names, class names, method names, and other code definitions from source files.'
 cbparameters:
   parameters:
     - name: path
@@ -21,9 +21,32 @@ data:
 <CBBaseInfo/> 
 <CBParameters/>
 
-### Example 
+## Examples
+
+### Basic Code Definition Extraction
+
+```js
+// Extract code definitions from current directory
+const result = await codebolt.fs.listCodeDefinitionNames('/home/user/projects');
+console.log('Code definitions found:', result);
+```
+
+### Extract from Current Directory
 
 ```js
-// Let's assume you want to list all code definition names in the /home/user/projects directory.
+// List all code definitions in current directory
+const codeDefResult = await codebolt.fs.listCodeDefinitionNames('.');
+console.log('✅ Code definitions in current directory:', codeDefResult);
 
-codebolt.fs.listCodeDefinitionNames('/home/user/projects');
+// Process the results
+if (codeDefResult.success && codeDefResult.result) {
+    console.log('Found code definitions:');
+    if (Array.isArray(codeDefResult.result)) {
+        codeDefResult.result.forEach((def, index) => {
+            console.log(`${index + 1}. ${def}`);
+        });
+    } else {
+        console.log('Result:', codeDefResult.result);
+    }
+}
+```