From 822b62ff459fa055c2824a1cdc742b483511f47c Mon Sep 17 00:00:00 2001
From: Luis Michaelis <me@lmichaelis.de>
Date: Sat, 30 Dec 2023 12:15:07 +0100
Subject: [PATCH] docs(Vfs): add documenation

---
 ZenKit/Vfs.cs | 80 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 76 insertions(+), 4 deletions(-)

diff --git a/ZenKit/Vfs.cs b/ZenKit/Vfs.cs
index b98c729..f8a60c0 100644
--- a/ZenKit/Vfs.cs
+++ b/ZenKit/Vfs.cs
@@ -1,13 +1,29 @@
 using System;
 using System.Collections.Generic;
+using System.IO;
 
 namespace ZenKit
 {
 	public enum VfsOverwriteBehavior
 	{
+		/// <summary>
+		///     Overwrite no conflicting nodes.
+		/// </summary>
 		None = 0,
+
+		/// <summary>
+		///     Overwrite all conflicting nodes.
+		/// </summary>
 		All = 1,
+
+		/// <summary>
+		///     Overwrite newer conflicting nodes.
+		/// </summary>
 		Newer = 2,
+
+		/// <summary>
+		///     Overwrite older conflicting nodes.
+		/// </summary>
 		Older = 3
 	}
 
@@ -112,6 +128,10 @@ public bool Remove(string name)
 		}
 	}
 
+	/// <summary>
+	///     An implementation of the ZenGin's virtual file system.
+	/// </summary>
+	/// <seealso href="https://zk.gothickit.dev/library/api/virtual-file-system/" />
 	public class Vfs
 	{
 		public Vfs()
@@ -120,14 +140,18 @@ public Vfs()
 			if (Handle == UIntPtr.Zero) throw new Exception("Failed to create Vfs");
 		}
 
-		public UIntPtr Handle { get; }
+		internal UIntPtr Handle { get; }
 
+		/// <summary>
+		///     The root node of the virtual file system structure.
+		/// </summary>
+		/// <exception cref="IOException">Thrown if accessing the native object fails.</exception>
 		public VfsNode Root
 		{
 			get
 			{
 				var node = Native.ZkVfs_getRoot(Handle);
-				if (node == UIntPtr.Zero) throw new Exception("Failed to get root Vfs node");
+				if (node == UIntPtr.Zero) throw new IOException("Failed to get root Vfs node");
 				return new VfsNode(node);
 			}
 		}
@@ -137,42 +161,90 @@ public VfsNode Root
 			Native.ZkVfs_del(Handle);
 		}
 
-		public void Mkdir(string path)
+		/// <summary>
+		///     Create all missing directories in the given path.
+		/// </summary>
+		/// <param name="path">Create all missing directories in the given path.</param>
+		/// <returns>The newly created directory or <c>null</c> if creating the directory fails..</returns>
+		public VfsNode? Mkdir(string path)
 		{
-			Native.ZkVfs_mkdir(Handle, path);
+			var p = Native.ZkVfs_mkdir(Handle, path);
+			return p == UIntPtr.Zero ? null : new VfsNode(p);
 		}
 
+		/// <summary>
+		///     Delete the file or directory at the given path
+		/// </summary>
+		/// <param name="path">The path of the node to delete.</param>
+		/// <returns><c>true</c> if removal was successful and <c>false</c> if not (ie. the file could not be found).</returns>
 		public bool Remove(string path)
 		{
 			return Native.ZkVfs_remove(Handle, path);
 		}
 
+		/// <summary>
+		///     <b>Mount the given file system node into the given directory.</b> When the given <paramref name="node" /> is a
+		///     directory, it is merged with any existing directory with the same name in the given <paramref name="parent" />
+		///     path.
+		/// </summary>
+		/// <param name="node">The file system node to mount.</param>
+		/// <param name="parent">The path of the parent node to mount into.</param>
+		/// <param name="overwrite">The behavior of the system when conflicting files are found.</param>
 		public void Mount(VfsNode node, string parent, VfsOverwriteBehavior overwrite)
 		{
 			Native.ZkVfs_mount(Handle, node.Handle, parent, overwrite);
 		}
 
+		/// <summary>
+		///     Mount a file or directory from the host file system into the Vfs.
+		/// </summary>
+		/// <remarks>If a path to a directory is provided, only its children are mounted, not the directory itself.</remarks>
+		/// <param name="path">The path of the file or directory to mount.</param>
+		/// <param name="parent">The path of the parent node to mount into.</param>
+		/// <param name="overwrite">The behavior of the system when conflicting files are found.</param>
 		public void Mount(string path, string parent, VfsOverwriteBehavior overwrite)
 		{
 			Native.ZkVfs_mountHost(Handle, path, parent, overwrite);
 		}
 
+		/// <summary>
+		///     <b>Mount the disk file in the given buffer into the file system.</b> The disk contents are mounted at the root node
+		///     of the file system and existing directories are merged together.
+		/// </summary>
+		/// <param name="buf">A buffer containing the disk file contents.</param>
+		/// <param name="overwrite">The behavior of the system when conflicting files are found.</param>
 		public void MountDisk(Read buf, VfsOverwriteBehavior overwrite)
 		{
 			Native.ZkVfs_mountDisk(Handle, buf.Handle, overwrite);
 		}
 
+		/// <summary>
+		///     <b>Mount the disk file at the given host path into the file system.</b> The disk contents are mounted at the root
+		///     node of the file system and existing directories are merged together.
+		/// </summary>
+		/// <param name="path">The path of the disk to mount.</param>
+		/// <param name="overwrite">The behavior of the system when conflicting files are found.</param>
 		public void MountDisk(string path, VfsOverwriteBehavior overwrite)
 		{
 			Native.ZkVfs_mountDiskHost(Handle, path, overwrite);
 		}
 
+		/// <summary>
+		///     Resolve the given path in the Vfs to a file system node.
+		/// </summary>
+		/// <param name="path">The path to the node to resolve.</param>
+		/// <returns>The node at the given path or <c>null</c> if the path could not be resolved.</returns>
 		public VfsNode? Resolve(string path)
 		{
 			var result = Native.ZkVfs_resolvePath(Handle, path);
 			return result == UIntPtr.Zero ? null : new VfsNode(result);
 		}
 
+		/// <summary>
+		///     Find the first node with the given name in the Vfs.
+		/// </summary>
+		/// <param name="name">The name of the node to find.</param>
+		/// <returns>The node with the given name or <c>null</c> if no node with the given name was found.</returns>
 		public VfsNode? Find(string name)
 		{
 			var result = Native.ZkVfs_findNode(Handle, name);