From f4944e1a176686b688097141ec276a8275aa46f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rados=C5=82aw=20Wa=C5=9Bko?= <radoslaw.wasko@enso.org>
Date: Fri, 1 Mar 2024 16:56:57 +0100
Subject: [PATCH] docs

---
 .../0.0.0-dev/src/Enso_Cloud/Enso_File.enso   | 21 +++++++++++++++++--
 .../enso_cloud/EnsoPathFileSystemSPI.java     |  4 ++++
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/distribution/lib/Standard/Base/0.0.0-dev/src/Enso_Cloud/Enso_File.enso b/distribution/lib/Standard/Base/0.0.0-dev/src/Enso_Cloud/Enso_File.enso
index 78f5040ec52c..292cff9e2c03 100644
--- a/distribution/lib/Standard/Base/0.0.0-dev/src/Enso_Cloud/Enso_File.enso
+++ b/distribution/lib/Standard/Base/0.0.0-dev/src/Enso_Cloud/Enso_File.enso
@@ -37,8 +37,25 @@ from project.System.File.Generic.File_Write_Strategy import generic_copy
 from project.System.File_Format import Auto_Detect, Bytes, File_Format, Plain_Text_Format
 
 type Enso_File
-    ## Resolves an `enso://` path to a file.
-    new : Text -> Enso_File
+    ## Resolves an `enso://` path and returns the corresponding `Enso_File`
+       instance.
+
+       Arguments:
+       - path: The `enso://` path to a file or directory.
+
+       ? Enso Cloud Paths
+
+         The paths consist of the organization (user) name followed by a path to
+         the file/directory delimited by `/`.
+         For example `enso://my_org/some_dir/some-file.txt`.
+
+       ! Work in progress - only existing resources
+
+         Currently the API is only able to resolve paths to existing files or
+         directories. This is a temporary limitation and it will be improved in
+         the future, alongside with implementing the capabilities to write new
+         files.
+    new : Text -> Enso_File ! Not_Found
     new (path : Text) =
         parsed = Enso_Path.parse path
         parent = parsed.resolve_parent
diff --git a/std-bits/base/src/main/java/org/enso/base/enso_cloud/EnsoPathFileSystemSPI.java b/std-bits/base/src/main/java/org/enso/base/enso_cloud/EnsoPathFileSystemSPI.java
index 54e6bb2568c7..bab84e1f251a 100644
--- a/std-bits/base/src/main/java/org/enso/base/enso_cloud/EnsoPathFileSystemSPI.java
+++ b/std-bits/base/src/main/java/org/enso/base/enso_cloud/EnsoPathFileSystemSPI.java
@@ -2,6 +2,10 @@
 
 import org.enso.base.file_system.FileSystemSPI;
 
+/** Registers the `enso://` protocol for resolving file paths.
+ * <p>
+ * See `Enso_File.new` for more information on path resolution.
+ */
 @org.openide.util.lookup.ServiceProvider(service = FileSystemSPI.class)
 public class EnsoPathFileSystemSPI extends FileSystemSPI {
   @Override