From aa009df7404805728b078a14f8f8956a198d1cec Mon Sep 17 00:00:00 2001
From: Jonathan Coates <git@squiddev.cc>
Date: Tue, 21 Dec 2021 14:39:08 +0000
Subject: [PATCH] Improve fs API introduction

Again, not perfect, but better than a single sentence.
---
 build.gradle                                  |  2 +-
 .../dan200/computercraft/core/apis/FSAPI.java | 37 ++++++++++++++++++-
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/build.gradle b/build.gradle
index ded8570c1..50527a954 100644
--- a/build.gradle
+++ b/build.gradle
@@ -158,7 +158,7 @@ accessTransformer file('src/testMod/resources/META-INF/accesstransformer.cfg')
 
     testModImplementation sourceSets.main.output
 
-    cctJavadoc 'cc.tweaked:cct-javadoc:1.4.4'
+    cctJavadoc 'cc.tweaked:cct-javadoc:1.4.5'
 }
 
 // Compile tasks
diff --git a/src/main/java/dan200/computercraft/core/apis/FSAPI.java b/src/main/java/dan200/computercraft/core/apis/FSAPI.java
index 6c3fd3522..550c23397 100644
--- a/src/main/java/dan200/computercraft/core/apis/FSAPI.java
+++ b/src/main/java/dan200/computercraft/core/apis/FSAPI.java
@@ -30,7 +30,36 @@
 import java.util.function.Function;
 
 /**
- * The FS API allows you to manipulate files and the filesystem.
+ * The FS API provides access to the computer's files and filesystem, allowing you to manipulate files, directories and
+ * paths. This includes:
+ *
+ * <ul>
+ * <li>**Reading and writing files:** Call {@link #open} to obtain a file "handle", which can be used to read from or
+ * write to a file.</li>
+ * <li>**Path manipulation:** {@link #combine}, {@link #getName} and {@link #getDir} allow you to manipulate file
+ * paths, joining them together or extracting components.</li>
+ * <li>**Querying paths:** For instance, checking if a file exists, or whether it's a directory. See {@link #getSize},
+ * {@link #exists}, {@link #isDir}, {@link #isReadOnly} and {@link #attributes}.</li>
+ * <li>**File and directory manipulation:** For instance, moving or copying files. See {@link #makeDir}, {@link #move},
+ * {@link #copy} and {@link #delete}.</li>
+ * </ul>
+ *
+ * :::note
+ * All functions in the API work on absolute paths, and do not take the @{shell.dir|current directory} into account.
+ * You can use @{shell.resolve} to convert a relative path into an absolute one.
+ * :::
+ *
+ * ## Mounts
+ * While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For
+ * instance, the {@link dan200.computercraft.shared.peripheral.diskdrive.DiskDrivePeripheral drive peripheral} mounts
+ * its disk's contents at {@code "disk/"}, {@code "disk1/"}, etc...
+ *
+ * You can see which mount a path belongs to with the {@link #getDrive} function. This returns {@code "hdd"} for the
+ * computer's main filesystem ({@code "/"}), {@code "rom"} for the rom ({@code "rom/"}).
+ *
+ * Most filesystems have a limited capacity, operations which would cause that capacity to be reached (such as writing
+ * an incredibly large file) will fail. You can see a mount's capacity with {@link #getCapacity} and the remaining
+ * space with {@link #getFreeSpace}.
  *
  * @cc.module fs
  */
@@ -440,6 +469,12 @@ public final Object[] open( String path, String mode ) throws LuaException
      * @return The name of the drive that the file is on; e.g. {@code hdd} for local files, or {@code rom} for ROM files.
      * @throws LuaException If the path doesn't exist.
      * @cc.treturn string The name of the drive that the file is on; e.g. {@code hdd} for local files, or {@code rom} for ROM files.
+     * @cc.usage Print the drives of a couple of mounts:
+     *
+     * <pre>{@code
+     * print("/: " .. fs.getDrive("/"))
+     * print("/rom/: " .. fs.getDrive("rom"))
+     * }</pre>
      */
     @LuaFunction
     public final Object[] getDrive( String path ) throws LuaException