refactor: format code and improve documentation examples

- Add working examples for Dir::find() and Dir::find_mut()
- Add examples for Metadata methods
- Remove redundant VirtualFileSystem trait documentation
- Fix and expand documentation examples in virtualfs
- Reorganize imports to be alphabetically sorted
- Group related imports using nested paths

monocore/lib/error.rs

@@ -1,6 +1,6 @@
+use ipldstore::{ipld, StoreError};
 use monofs::FsError;
 use monoutils::MonoutilsError;
-use ipldstore::{ipld, StoreError};
 use nix::errno::Errno;
 use sqlx::migrate::MigrateError;
 use std::{

monocore/lib/management/rootfs.rs

@@ -1,16 +1,19 @@
 use async_recursion::async_recursion;
 use chrono::{TimeZone, Utc};
-use ipldstore::ipld::ipld::Ipld;
-use ipldstore::{ipld::cid::Cid, IpldStore};
+use ipldstore::{
+    ipld::{cid::Cid, ipld::Ipld},
+    IpldStore,
+};
 use monofs::filesystem::{
     Dir, Entity, File, Metadata, SymPathLink, UNIX_ATIME_KEY, UNIX_GID_KEY, UNIX_MODE_KEY,
     UNIX_MTIME_KEY, UNIX_UID_KEY,
 };
-use std::fs;
-use std::os::unix::fs::{MetadataExt, PermissionsExt};
-use std::path::Path;
-use tokio::fs::File as TokioFile;
-use tokio::io::BufReader;
+use std::{
+    fs,
+    os::unix::fs::{MetadataExt, PermissionsExt},
+    path::Path,
+};
+use tokio::{fs::File as TokioFile, io::BufReader};
 
 use crate::MonocoreResult;
 

monofs/examples/file.rs

@@ -21,8 +21,8 @@
 //! cargo run --example file
 //! ```
 
-use monofs::filesystem::File;
 use ipldstore::{MemoryStore, Storable};
+use monofs::filesystem::File;
 use tokio::io::{AsyncReadExt, AsyncWriteExt, BufReader};
 
 //--------------------------------------------------------------------------------------------------
@@ -49,7 +49,6 @@ async fn main() -> anyhow::Result<()> {
     drop(output_stream);
     println!("Wrote content to file");
 
-
     // Read content from the file
     let input_stream = file.get_input_stream().await?;
     let mut buffer = Vec::new();

virtualfs/lib/filesystem.rs

@@ -18,28 +18,6 @@ use tokio::io::AsyncRead;
 /// files and directories in an abstract file system. This abstraction allows for different
 /// implementations such as in-memory filesystems, overlay filesystems, or traditional disk-based
 /// filesystems while maintaining a consistent interface.
-///
-/// ## Examples
-///
-/// ```rust,no_run
-/// use async_trait::async_trait;
-/// use std::path::Path;
-///
-/// #[async_trait]
-/// impl VirtualFileSystem for MyCustomFs {
-///     async fn exists(&self, path: impl AsRef<Path>) -> VfsResult<bool> {
-///         // Implementation here
-///     }
-///     // ... other method implementations ...
-/// }
-/// ```
-///
-/// ## Design Notes
-///
-/// - All operations are asynchronous and return `VfsResult<T>` to handle potential errors
-/// - Paths are accepted as any type that can be converted to a `Path`
-/// - File operations support offset-based reading and writing for random access
-/// - Directory operations return iterators over path entries
 #[async_trait]
 pub trait VirtualFileSystem {
     /// Checks if a file or directory exists at the specified path.

virtualfs/lib/implementations/memoryfs.rs

@@ -335,15 +335,22 @@ impl Dir {
     ///
     /// ## Examples
     ///
-    /// ```rust,no_run
-    /// use std::path::Path;
-    /// ## use virtualfs::{Dir, VfsResult};
-    ///
-    /// ## fn example(dir: Dir) -> VfsResult<()> {
-    /// // Find an entity at path "foo/bar"
-    /// let entity = dir.find("foo/bar")?;
-    /// ## Ok(())
-    /// ## }
+    /// ```rust
+    /// # use std::path::Path;
+    /// # use virtualfs::{Dir, Entity, File, PathSegment, VfsResult};
+    /// #
+    /// # fn main() -> VfsResult<()> {
+    /// # let mut dir = Dir::new();
+    /// # dir.put(
+    /// #     PathSegment::try_from("foo").unwrap(),
+    /// #     Entity::Dir(Dir::new())
+    /// # )?;
+    /// #
+    /// // Find an entity at path "foo"
+    /// let entity = dir.find("foo")?.unwrap();
+    /// assert!(matches!(entity, Entity::Dir(_)));
+    /// # Ok(())
+    /// # }
     /// ```
     pub fn find(&self, path: impl AsRef<Path> + Send + Sync) -> VfsResult<Option<&Entity>> {
         let path = path.as_ref();
@@ -409,14 +416,20 @@ impl Dir {
     ///
     /// ## Examples
     ///
-    /// ```rust,no_run
-    /// use std::path::Path;
-    /// # use virtualfs::{Dir, VfsResult};
-    ///
-    /// # fn example(dir: &mut Dir) -> VfsResult<()> {
-    /// // Find and modify an entity at path "foo/bar"
-    /// if let Some(entity) = dir.find_mut("foo/bar")? {
-    ///     // Modify the entity
+    /// ```rust
+    /// # use std::path::Path;
+    /// # use virtualfs::{Dir, Entity, File, PathSegment, VfsResult};
+    /// #
+    /// # fn main() -> VfsResult<()> {
+    /// # let mut dir = Dir::new();
+    /// # dir.put(
+    /// #     PathSegment::try_from("foo").unwrap(),
+    /// #     Entity::Dir(Dir::new())
+    /// # )?;
+    /// #
+    /// // Find and modify an entity at path "foo"
+    /// if let Some(entity) = dir.find_mut("foo")? {
+    ///     assert!(matches!(entity, Entity::Dir(_)));
     /// }
     /// # Ok(())
     /// # }

virtualfs/lib/metadata.rs

@@ -294,6 +294,14 @@ impl Metadata {
     /// - size: 0 bytes
     /// - created_at: current UTC time
     /// - modified_at: current UTC time
+    ///
+    /// ## Examples
+    /// ```rust
+    /// use virtualfs::{Metadata, ModeType};
+    ///
+    /// let metadata = Metadata::new(ModeType::File);
+    /// assert_eq!(metadata.get_size(), 0);
+    /// ```
     pub fn new(
         #[cfg(unix)] entity_type: ModeType,
         #[cfg(not(unix))] entity_type: EntityType,
@@ -339,9 +347,9 @@ impl Metadata {
     ///
     /// ## Examples
     /// ```rust
-    /// use virtualfs::{Metadata, User, Group, Other};
+    /// use virtualfs::{Metadata, ModeType, User, Group, Other};
     ///
-    /// let mut metadata = Metadata::new();
+    /// let mut metadata = Metadata::new(ModeType::File);
     /// metadata.set_permissions(User::RW | Group::R | Other::R);
     /// ```
     #[cfg(unix)]
@@ -365,11 +373,11 @@ impl Metadata {
     ///
     /// ## Examples
     /// ```rust
-    /// use virtualfs::Metadata;
+    /// use virtualfs::{Metadata, ModeType};
     ///
-    /// let mut metadata = Metadata::new();
-    /// metadata.set_entity_type(EntityType::Directory);
-    /// assert_eq!(metadata.get_entity_type(), &EntityType::Directory);
+    /// let mut metadata = Metadata::new(ModeType::File);
+    /// metadata.set_entity_type(ModeType::Directory);
+    /// assert_eq!(metadata.get_entity_type(), &ModeType::Directory);
     /// ```
     #[cfg(not(unix))]
     pub fn set_entity_type(&mut self, entity_type: EntityType) {
@@ -380,9 +388,9 @@ impl Metadata {
     ///
     /// ## Examples
     /// ```rust
-    /// use virtualfs::Metadata;
+    /// use virtualfs::{Metadata, ModeType};
     ///
-    /// let mut metadata = Metadata::new();
+    /// let mut metadata = Metadata::new(ModeType::File);
     /// metadata.set_size(100);
     /// assert_eq!(metadata.get_size(), 100);
     /// ```