Add a whole tonne of documentation

There's a bit of duplication here, so we might try to clean this up, but
it's a good starting point.

build.gradle

@@ -122,7 +122,7 @@ dependencies {
 
     deployerJars "org.apache.maven.wagon:wagon-ssh:3.0.0"
 
-    cctJavadoc 'cc.tweaked:cct-javadoc:1.0.0'
+    cctJavadoc 'cc.tweaked:cct-javadoc:1.1.0'
 }
 
 // Compile tasks

doc/stub/fs.lua

@@ -14,27 +14,21 @@
 -- @see getDrive
 function isDriveRoot(path) end
 
--- Defined in bios.lua
+--[[- Provides completion for a file or directory name, suitable for use with
-function complete(sPath, sLocation, bIncludeFiles, bIncludeDirs) end
+@{read}.
 
---- A file handle which can be read from.
+When a directory is a possible candidate for completion, two entries are
---
+included - one with a trailing slash (indicating that entries within this
--- @type ReadHandle
+directory exist) and one without it (meaning this entry is an immediate
--- @see fs.open
+completion candidate). `include_dirs` can be set to @{false} to only include
-local ReadHandle = {}
+those with a trailing slash.
-function ReadHandle.read(count) end
-function ReadHandle.readAll() end
-function ReadHandle.readLine(with_trailing) end
-function ReadHandle.seek(whence, offset) end
-function ReadHandle.close() end
 
---- A file handle which can be written to.
+@tparam string path The path to complete.
---
+@tparam string location The location where paths are resolved from.
--- @type WriteHandle
+@tparam[opt] boolean include_files When @{false}, only directories will be
--- @see fs.open
+included in the returned list.
-local WriteHandle = {}
+@tparam[opt] boolean include_dirs When @{false}, "raw" directories will not be
-function WriteHandle.write(text) end
+included in the returned list.
-function WriteHandle.writeLine(text) end
+@treturn { string... } A list of possible completion candidates.
-function WriteHandle.flush(text) end
+]]
-function WriteHandle.seek(whence, offset) end
+function complete(path, location, include_files, include_dirs) end
-function WriteHandle.close() end

doc/stub/http.lua

@@ -93,47 +93,6 @@ function get(...) end
 -- @treturn Response|nil The failing http response, if available.
 function post(...) end
 
---- A http response. This acts very much like a @{fs.ReadHandle|file}, though
--- provides some http specific methods.
---
--- #### `http_success` event
--- #### `http_failure` event
---
--- @type Response
--- @see http.request On how to make a http request.
-local Response = {}
-
---- Returns the response code and response message returned by the server
---
--- @treturn number The response code (i.e. 200)
--- @treturn string The response message (i.e. "OK")
-function Response.getResponseCode() end
-
---- Get a table containing the response's headers, in a format similar to that
--- required by @{http.request}. If multiple headers are sent with the same
--- name, they will be combined with a comma.
---
--- @treturn { [string]=string } The response's headers.
--- Make a request to [example.computercraft.cc](https://example.computercraft.cc),
--- and print the returned headers.
--- ```lua
--- local request = http.get("https://example.computercraft.cc")
--- print(textutils.serialize(request.getResponseHeaders()))
--- -- => {
--- --   [ "Content-Type" ] = "text/plain; charset=utf8",
--- --   [ "content-length" ] = 17,
--- --   ...
--- -- }
--- request.close()
--- ```
-function Response.getResponseHeaders() end
-
-function Response.read(count) end
-function Response.readAll() end
-function Response.readLine(with_trailing) end
-function Response.seek(whence, offset) end
-function Response.close() end
-
 --- Asynchronously determine whether a URL can be requested.
 --
 -- If this returns `true`, one should also listen for [`http_check`

doc/stub/term.lua

@@ -1,50 +0,0 @@
-function write(text) end
-function scroll(lines) end
-function setCursorPos(x, y) end
-function setCursorBlink(blink) end
-function getCursorPos() end
-function getSize() end
-function clear() end
-function clearLine() end
-function setTextColour(colour) end
-setTextColor = setTextColour
-function setBackgroundColour(colour) end
-setBackgroundColor = setBackgroundColour
-function isColour() end
-isColor = isColour
-function getTextColour() end
-getTextColor = getTextColor
-function getBackgroundColour() end
-getBackgroundColor = getBackgroundColour
-function blit(text, text_colours, background_colours) end
-function setPaletteColour(colour, ...) end
-setPaletteColor = setPaletteColour
-function getPaletteColour(colour, ...) end
-getPaletteColor = getPaletteColour
-
---- @type Redirect
-local Redirect = {}
-
-Redirect.write = write
-Redirect.scroll = scroll
-Redirect.setCursorPos = setCursorPos
-Redirect.setCursorBlink = setCursorBlink
-Redirect.getCursorPos = getCursorPos
-Redirect.getSize = getSize
-Redirect.clear = clear
-Redirect.clearLine = clearLine
-Redirect.setTextColour = setTextColour
-Redirect.setTextColor = setTextColor
-Redirect.setBackgroundColour = setBackgroundColour
-Redirect.setBackgroundColor = setBackgroundColor
-Redirect.isColour = isColour
-Redirect.isColor = isColor
-Redirect.getTextColour = getTextColour
-Redirect.getTextColor = getTextColor
-Redirect.getBackgroundColour = getBackgroundColour
-Redirect.getBackgroundColor = getBackgroundColor
-Redirect.blit = blit
-Redirect.setPaletteColour = setPaletteColour
-Redirect.setPaletteColor = setPaletteColor
-Redirect.getPaletteColour = getPaletteColour
-Redirect.getPaletteColor = getPaletteColor

illuaminate.sexp

@@ -76,15 +76,10 @@
 ;; Suppress warnings for currently undocumented modules.
 (at
   (; Java APIs
-   /doc/stub/fs.lua
    /doc/stub/http.lua
    /doc/stub/os.lua
-   /doc/stub/term.lua
    /doc/stub/turtle.lua
    ; Java generated APIs
-   /doc/javadoc/fs.lua
-   /doc/javadoc/http.lua
-   /doc/javadoc/os.lua
    /doc/javadoc/turtle.lua
    ; Peripherals
    /doc/javadoc/drive.lua
@@ -101,7 +96,8 @@
   (/src/main/resources/*/computercraft/lua/rom/apis/textutils.lua
    /src/main/resources/*/computercraft/lua/rom/modules/main/cc/completion.lua
    /src/main/resources/*/computercraft/lua/rom/modules/main/cc/shell/completion.lua
-   /src/main/resources/*/computercraft/lua/rom/programs/shell.lua)
+   /src/main/resources/*/computercraft/lua/rom/programs/shell.lua
+   /doc/stub/fs.lua)
   (linters -doc:unresolved-reference))
 
 (at /src/test/resources/test-rom

src/main/java/dan200/computercraft/core/apis/TermAPI.java

@@ -5,6 +5,7 @@
  */
 package dan200.computercraft.core.apis;
 
+import dan200.computercraft.api.lua.IArguments;
 import dan200.computercraft.api.lua.ILuaAPI;
 import dan200.computercraft.api.lua.LuaException;
 import dan200.computercraft.api.lua.LuaFunction;
@@ -45,6 +46,7 @@ public class TermAPI extends TermMethods implements ILuaAPI
      * @cc.treturn number The red channel, will be between 0 and 1.
      * @cc.treturn number The green channel, will be between 0 and 1.
      * @cc.treturn number The blue channel, will be between 0 and 1.
+     * @see TermMethods#setPaletteColour(IArguments) To change the palette colour.
      */
     @LuaFunction( { "nativePaletteColour", "nativePaletteColor" } )
     public final Object[] nativePaletteColour( int colour ) throws LuaException

src/main/java/dan200/computercraft/core/apis/TermMethods.java

@@ -20,7 +20,6 @@ import javax.annotation.Nonnull;
  * A base class for all objects which interact with a terminal. Namely the {@link TermAPI} and monitors.
  *
  * @cc.module term.Redirect
- * @hidden
  */
 public abstract class TermMethods
 {
@@ -40,6 +39,16 @@ public abstract class TermMethods
 
     public abstract boolean isColour() throws LuaException;
 
+    /**
+     * Write {@code text} at the current cursor position, moving the cursor to the end of the text.
+     *
+     * Unlike functions like {@code write} and {@code print}, this does not wrap the text - it simply copies the
+     * text to the current terminal line.
+     *
+     * @param arguments The text to write.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.param text The text to write.
+     */
     @LuaFunction
     public final void write( IArguments arguments ) throws LuaException
     {
@@ -52,12 +61,29 @@ public abstract class TermMethods
         }
     }
 
+    /**
+     * Move all positions up (or down) by {@code y} pixels.
+     *
+     * Every pixel in the terminal will be replaced by the line {@code y} pixels below it. If {@code y} is negative, it
+     * will copy pixels from above instead.
+     *
+     * @param y The number of lines to move up by. This may be a negative number.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     */
     @LuaFunction
     public final void scroll( int y ) throws LuaException
     {
         getTerminal().scroll( y );
     }
 
+    /**
+     * Get the position of the cursor.
+     *
+     * @return The cursor's position.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.treturn number The x position of the cursor.
+     * @cc.treturn number The y position of the cursor.
+     */
     @LuaFunction
     public final Object[] getCursorPos() throws LuaException
     {
@@ -65,6 +91,13 @@ public abstract class TermMethods
         return new Object[] { terminal.getCursorX() + 1, terminal.getCursorY() + 1 };
     }
 
+    /**
+     * Set the position of the cursor. {@link #write(IArguments) terminal writes} will begin from this position.
+     *
+     * @param x The new x position of the cursor.
+     * @param y The new y position of the cursor.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     */
     @LuaFunction
     public final void setCursorPos( int x, int y ) throws LuaException
     {
@@ -75,12 +108,24 @@ public abstract class TermMethods
         }
     }
 
+    /**
+     * Checks if the cursor is currently blinking.
+     *
+     * @return If the cursor is blinking.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     */
     @LuaFunction
     public final boolean getCursorBlink() throws LuaException
     {
         return getTerminal().getCursorBlink();
     }
 
+    /**
+     * Sets whether the cursor should be visible (and blinking) at the current {@link #getCursorPos() cursor position}.
+     *
+     * @param blink Whether the cursor should blink.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     */
     @LuaFunction
     public final void setCursorBlink( boolean blink ) throws LuaException
     {
@@ -91,6 +136,14 @@ public abstract class TermMethods
         }
     }
 
+    /**
+     * Get the size of the terminal.
+     *
+     * @return The terminal's size.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.treturn number The terminal's width.
+     * @cc.treturn number The terminal's height.
+     */
     @LuaFunction
     public final Object[] getSize() throws LuaException
     {
@@ -98,24 +151,49 @@ public abstract class TermMethods
         return new Object[] { terminal.getWidth(), terminal.getHeight() };
     }
 
+    /**
+     * Clears the terminal, filling it with the {@link #getBackgroundColour() current background colour}.
+     *
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     */
     @LuaFunction
     public final void clear() throws LuaException
     {
         getTerminal().clear();
     }
 
+    /**
+     * Clears the line the cursor is currently on, filling it with the {@link #getBackgroundColour() current background
+     * colour}.
+     *
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     */
     @LuaFunction
     public final void clearLine() throws LuaException
     {
         getTerminal().clearLine();
     }
 
+    /**
+     * Return the colour that new text will be written as.
+     *
+     * @return The current text colour.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.see colors For a list of colour constants, returned by this function.
+     */
     @LuaFunction( { "getTextColour", "getTextColor" } )
     public final int getTextColour() throws LuaException
     {
         return encodeColour( getTerminal().getTextColour() );
     }
 
+    /**
+     * Set the colour that new text will be written as.
+     *
+     * @param colourArg The new text colour.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.see colors For a list of colour constants.
+     */
     @LuaFunction( { "setTextColour", "setTextColor" } )
     public final void setTextColour( int colourArg ) throws LuaException
     {
@@ -127,12 +205,28 @@ public abstract class TermMethods
         }
     }
 
+    /**
+     * Return the current background colour. This is used when {@link #write writing text} and {@link #clear clearing}
+     * the terminal.
+     *
+     * @return The current background colour.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.see colors For a list of colour constants, returned by this function.
+     */
     @LuaFunction( { "getBackgroundColour", "getBackgroundColor" } )
     public final int getBackgroundColour() throws LuaException
     {
         return encodeColour( getTerminal().getBackgroundColour() );
     }
 
+    /**
+     * Set the current background colour. This is used when {@link #write writing text} and {@link #clear clearing} the
+     * terminal.
+     *
+     * @param colourArg The new background colour.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.see colors For a list of colour constants.
+     */
     @LuaFunction( { "setBackgroundColour", "setBackgroundColor" } )
     public final void setBackgroundColour( int colourArg ) throws LuaException
     {
@@ -144,12 +238,41 @@ public abstract class TermMethods
         }
     }
 
+    /**
+     * Determine if this terminal supports colour.
+     *
+     * Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be
+     * displayed in greyscale.
+     *
+     * @return Whether this terminal supports colour.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     */
     @LuaFunction( { "isColour", "isColor" } )
     public final boolean getIsColour() throws LuaException
     {
         return isColour();
     }
 
+    /**
+     * Writes {@code text} to the terminal with the specific foreground and background characters.
+     *
+     * As with {@link #write(IArguments)}, the text will be written at the current cursor location, with the cursor
+     * moving to the end of the text.
+     *
+     * {@code textColour} and {@code backgroundColour} must both be strings the same length as {@code text}. All
+     * characters represent a single hexadecimal digit, which is converted to one of CC's colours. For instance,
+     * {@code "a"} corresponds to purple.
+     *
+     * @param text             The text to write.
+     * @param textColour       The corresponding text colours.
+     * @param backgroundColour The corresponding background colours.
+     * @throws LuaException If the three inputs are not the same length.
+     * @cc.see colors For a list of colour constants, and their hexadecimal values.
+     * @cc.usage Prints "Hello, world!" in rainbow text.
+     * <pre>{@code
+     * term.blit("Hello, world!","01234456789ab","0000000000000")
+     * }</pre>
+     */
     @LuaFunction
     public final void blit( String text, String textColour, String backgroundColour ) throws LuaException
     {
@@ -166,6 +289,38 @@ public abstract class TermMethods
         }
     }
 
+    /**
+     * Set the palette for a specific colour.
+     *
+     * ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you
+     * can make @{colors.red} <em>more red</em> by setting its palette to #FF0000. This does now allow you to draw more
+     * colours - you are still limited to 16 on the screen at one time - but you can change <em>which</em> colours are
+     * used.
+     *
+     * @param args The new palette values.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.tparam [1] number index The colour whose palette should be changed.
+     * @cc.tparam number colour A 24-bit integer representing the RGB value of the colour. For instance the integer
+     * `0xFF0000` corresponds to the colour #FF0000.
+     * @cc.tparam [2] number index The colour whose palette should be changed.
+     * @cc.tparam number r The intensity of the red channel, between 0 and 1.
+     * @cc.tparam number g The intensity of the green channel, between 0 and 1.
+     * @cc.tparam number b The intensity of the blue channel, between 0 and 1.
+     * @cc.usage Change the @{colors.red|red colour} from the default #CC4C4C to #FF0000.
+     * <pre>{@code
+     * term.setPaletteColour(colors.red, 0xFF0000)
+     * term.setTextColour(colors.red)
+     * print("Hello, world!")
+     * }</pre>
+     * @cc.usage As above, but specifying each colour channel separately.
+     * <pre>{@code
+     * term.setPaletteColour(colors.red, 1, 0, 0)
+     * term.setTextColour(colors.red)
+     * print("Hello, world!")
+     * }</pre>
+     * @cc.see colors.unpackRGB To convert from the 24-bit format to three separate channels.
+     * @cc.see colors.packRGB To convert from three separate channels to the 24-bit format.
+     */
     @LuaFunction( { "setPaletteColour", "setPaletteColor" } )
     public final void setPaletteColour( IArguments args ) throws LuaException
     {
@@ -185,6 +340,16 @@ public abstract class TermMethods
         }
     }
 
+    /**
+     * Get the current palette for a specific colour.
+     *
+     * @param colourArg The colour whose palette should be fetched.
+     * @return The resulting colour.
+     * @throws LuaException (hidden) If the terminal cannot be found.
+     * @cc.treturn number The red channel, will be between 0 and 1.
+     * @cc.treturn number The green channel, will be between 0 and 1.
+     * @cc.treturn number The blue channel, will be between 0 and 1.
+     */
     @LuaFunction( { "getPaletteColour", "getPaletteColor" } )
     public final Object[] getPaletteColour( int colourArg ) throws LuaException
     {
@@ -192,12 +357,8 @@ public abstract class TermMethods
         Terminal terminal = getTerminal();
         synchronized( terminal )
         {
-            if( terminal.getPalette() != null )
+            return ArrayUtils.toObject( terminal.getPalette().getColour( colour ) );
-            {
-                return ArrayUtils.toObject( terminal.getPalette().getColour( colour ) );
-            }
         }
-        return null;
     }
 
     public static int parseColour( int colour ) throws LuaException
@@ -216,10 +377,7 @@ public abstract class TermMethods
 
     public static void setColour( Terminal terminal, int colour, double r, double g, double b )
     {
-        if( terminal.getPalette() != null )
+        terminal.getPalette().setColour( colour, r, g, b );
-        {
+        terminal.setChanged();
-            terminal.getPalette().setColour( colour, r, g, b );
-            terminal.setChanged();
-        }
     }
 }

src/main/java/dan200/computercraft/core/apis/handles/BinaryReadableHandle.java

@@ -5,7 +5,6 @@
  */
 package dan200.computercraft.core.apis.handles;
 
-import dan200.computercraft.api.lua.IArguments;
 import dan200.computercraft.api.lua.LuaException;
 import dan200.computercraft.api.lua.LuaFunction;
 
@@ -19,6 +18,12 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * A file handle opened with {@link dan200.computercraft.core.apis.FSAPI#open(String, String)} with the {@code "rb"}
+ * mode.
+ *
+ * @cc.module fs.BinaryReadHandle
+ */
 public class BinaryReadableHandle extends HandleGeneric
 {
     private static final int BUFFER_SIZE = 8192;
@@ -27,7 +32,7 @@ public class BinaryReadableHandle extends HandleGeneric
     final SeekableByteChannel seekable;
     private final ByteBuffer single = ByteBuffer.allocate( 1 );
 
-    protected BinaryReadableHandle( ReadableByteChannel reader, SeekableByteChannel seekable, Closeable closeable )
+    BinaryReadableHandle( ReadableByteChannel reader, SeekableByteChannel seekable, Closeable closeable )
     {
         super( closeable );
         this.reader = reader;
@@ -45,6 +50,18 @@ public class BinaryReadableHandle extends HandleGeneric
         return of( channel, channel );
     }
 
+    /**
+     * Read a number of bytes from this file.
+     *
+     * @param countArg The number of bytes to read. When absent, a single byte will be read <em>as a number</em>. This
+     *                 may be 0 to determine we are at the end of the file.
+     * @return The read bytes.
+     * @throws LuaException When trying to read a negative number of bytes.
+     * @throws LuaException If the file has been closed.
+     * @cc.treturn [1] nil If we are at the end of the file.
+     * @cc.treturn [2] number The value of the byte read. This is returned when the {@code count} is absent.
+     * @cc.treturn [3] string The bytes read as a string. This is returned when the {@code count} is given.
+     */
     @LuaFunction
     public final Object[] read( Optional<Integer> countArg ) throws LuaException
     {
@@ -122,6 +139,13 @@ public class BinaryReadableHandle extends HandleGeneric
         }
     }
 
+    /**
+     * Read the remainder of the file.
+     *
+     * @return The file, or {@code null} if at the end of it.
+     * @throws LuaException If the file has been closed.
+     * @cc.treturn string|nil The remaining contents of the file, or {@code nil} if we are at the end.
+     */
     @LuaFunction
     public final Object[] readAll() throws LuaException
     {
@@ -151,6 +175,14 @@ public class BinaryReadableHandle extends HandleGeneric
         }
     }
 
+    /**
+     * Read a line from the file.
+     *
+     * @param withTrailingArg Whether to include the newline characters with the returned string. Defaults to {@code false}.
+     * @return The read string.
+     * @throws LuaException If the file has been closed.
+     * @cc.treturn string|nil The read line or {@code nil} if at the end of the file.
+     */
     @LuaFunction
     public final Object[] readLine( Optional<Boolean> withTrailingArg ) throws LuaException
     {
@@ -205,16 +237,34 @@ public class BinaryReadableHandle extends HandleGeneric
 
     public static class Seekable extends BinaryReadableHandle
     {
-        public Seekable( SeekableByteChannel seekable, Closeable closeable )
+        Seekable( SeekableByteChannel seekable, Closeable closeable )
         {
             super( seekable, seekable, closeable );
         }
 
+        /**
+         * Seek to a new position within the file, changing where bytes are written to. The new position is an offset
+         * given by {@code offset}, relative to a start position determined by {@code whence}:
+         *
+         * - {@code "set"}: {@code offset} is relative to the beginning of the file.
+         * - {@code "cur"}: Relative to the current position. This is the default.
+         * - {@code "end"}: Relative to the end of the file.
+         *
+         * In case of success, {@code seek} returns the new file position from the beginning of the file.
+         *
+         * @param whence Where the offset is relative to.
+         * @param offset The offset to seek to.
+         * @return The new position.
+         * @throws LuaException If the file has been closed.
+         * @cc.treturn [1] number The new position.
+         * @cc.treturn [2] nil If seeking failed.
+         * @cc.treturn string The reason seeking failed.
+         */
         @LuaFunction
-        public final Object[] seek( IArguments arguments ) throws LuaException
+        public final Object[] seek( Optional<String> whence, Optional<Long> offset ) throws LuaException
         {
             checkOpen();
-            return handleSeek( seekable, arguments );
+            return handleSeek( seekable, whence, offset );
         }
     }
 }

src/main/java/dan200/computercraft/core/apis/handles/BinaryWritableHandle.java

@@ -16,7 +16,14 @@ import java.nio.ByteBuffer;
 import java.nio.channels.FileChannel;
 import java.nio.channels.SeekableByteChannel;
 import java.nio.channels.WritableByteChannel;
+import java.util.Optional;
 
+/**
+ * A file handle opened by {@link dan200.computercraft.core.apis.FSAPI#open} using the {@code "wb"} or {@code "ab"}
+ * modes.
+ *
+ * @cc.module fs.BinaryWriteHandle
+ */
 public class BinaryWritableHandle extends HandleGeneric
 {
     private final WritableByteChannel writer;
@@ -41,6 +48,14 @@ public class BinaryWritableHandle extends HandleGeneric
         return of( channel, channel );
     }
 
+    /**
+     * Write a string or byte to the file.
+     *
+     * @param arguments The value to write.
+     * @throws LuaException If the file has been closed.
+     * @cc.tparam [1] number The byte to write.
+     * @cc.tparam [2] string The string to write.
+     */
     @LuaFunction
     public final void write( IArguments arguments ) throws LuaException
     {
@@ -72,6 +87,11 @@ public class BinaryWritableHandle extends HandleGeneric
         }
     }
 
+    /**
+     * Save the current file without closing it.
+     *
+     * @throws LuaException If the file has been closed.
+     */
     @LuaFunction
     public final void flush() throws LuaException
     {
@@ -93,11 +113,29 @@ public class BinaryWritableHandle extends HandleGeneric
             super( seekable, seekable, closeable );
         }
 
+        /**
+         * Seek to a new position within the file, changing where bytes are written to. The new position is an offset
+         * given by {@code offset}, relative to a start position determined by {@code whence}:
+         *
+         * - {@code "set"}: {@code offset} is relative to the beginning of the file.
+         * - {@code "cur"}: Relative to the current position. This is the default.
+         * - {@code "end"}: Relative to the end of the file.
+         *
+         * In case of success, {@code seek} returns the new file position from the beginning of the file.
+         *
+         * @param whence Where the offset is relative to.
+         * @param offset The offset to seek to.
+         * @return The new position.
+         * @throws LuaException If the file has been closed.
+         * @cc.treturn [1] number The new position.
+         * @cc.treturn [2] nil If seeking failed.
+         * @cc.treturn string The reason seeking failed.
+         */
         @LuaFunction
-        public final Object[] seek( IArguments args ) throws LuaException
+        public final Object[] seek( Optional<String> whence, Optional<Long> offset ) throws LuaException
         {
             checkOpen();
-            return handleSeek( seekable, args );
+            return handleSeek( seekable, whence, offset );
         }
     }
 }

src/main/java/dan200/computercraft/core/apis/handles/EncodedReadableHandle.java

@@ -20,6 +20,12 @@ import java.nio.charset.CodingErrorAction;
 import java.nio.charset.StandardCharsets;
 import java.util.Optional;
 
+/**
+ * A file handle opened with {@link dan200.computercraft.core.apis.FSAPI#open(String, String)} with the {@code "r"}
+ * mode.
+ *
+ * @cc.module fs.ReadHandle
+ */
 public class EncodedReadableHandle extends HandleGeneric
 {
     private static final int BUFFER_SIZE = 8192;
@@ -37,6 +43,14 @@ public class EncodedReadableHandle extends HandleGeneric
         this( reader, reader );
     }
 
+    /**
+     * Read a line from the file.
+     *
+     * @param withTrailingArg Whether to include the newline characters with the returned string. Defaults to {@code false}.
+     * @return The read string.
+     * @throws LuaException If the file has been closed.
+     * @cc.treturn string|nil The read line or {@code nil} if at the end of the file.
+     */
     @LuaFunction
     public final Object[] readLine( Optional<Boolean> withTrailingArg ) throws LuaException
     {
@@ -62,6 +76,13 @@ public class EncodedReadableHandle extends HandleGeneric
         }
     }
 
+    /**
+     * Read the remainder of the file.
+     *
+     * @return The file, or {@code null} if at the end of it.
+     * @throws LuaException If the file has been closed.
+     * @cc.treturn nil|string The remaining contents of the file, or {@code nil} if we are at the end.
+     */
     @LuaFunction
     public final Object[] readAll() throws LuaException
     {
@@ -87,6 +108,15 @@ public class EncodedReadableHandle extends HandleGeneric
         }
     }
 
+    /**
+     * Read a number of characters from this file.
+     *
+     * @param countA The number of characters to read, defaulting to 1.
+     * @return The read characters.
+     * @throws LuaException When trying to read a negative number of characters.
+     * @throws LuaException If the file has been closed.
+     * @cc.treturn string|nil The read characters, or {@code nil} if at the of the file.
+     */
     @LuaFunction
     public final Object[] read( Optional<Integer> countA ) throws LuaException
     {

src/main/java/dan200/computercraft/core/apis/handles/EncodedWritableHandle.java

@@ -21,6 +21,11 @@ import java.nio.charset.CharsetEncoder;
 import java.nio.charset.CodingErrorAction;
 import java.nio.charset.StandardCharsets;
 
+/**
+ * A file handle opened by {@link dan200.computercraft.core.apis.FSAPI#open} using the {@code "w"} or {@code "a"} modes.
+ *
+ * @cc.module fs.WriteHandle
+ */
 public class EncodedWritableHandle extends HandleGeneric
 {
     private final BufferedWriter writer;
@@ -31,6 +36,13 @@ public class EncodedWritableHandle extends HandleGeneric
         this.writer = writer;
     }
 
+    /**
+     * Write a string of characters to the file.
+     *
+     * @param args The value to write.
+     * @throws LuaException If the file has been closed.
+     * @cc.param The value to write to the file.
+     */
     @LuaFunction
     public final void write( IArguments args ) throws LuaException
     {
@@ -46,6 +58,13 @@ public class EncodedWritableHandle extends HandleGeneric
         }
     }
 
+    /**
+     * Write a string of characters to the file, follwing them with a new line character.
+     *
+     * @param args The value to write.
+     * @throws LuaException If the file has been closed.
+     * @cc.param The value to write to the file.
+     */
     @LuaFunction
     public final void writeLine( IArguments args ) throws LuaException
     {
@@ -62,6 +81,11 @@ public class EncodedWritableHandle extends HandleGeneric
         }
     }
 
+    /**
+     * Save the current file without closing it.
+     *
+     * @throws LuaException If the file has been closed.
+     */
     @LuaFunction
     public final void flush() throws LuaException
     {

src/main/java/dan200/computercraft/core/apis/handles/HandleGeneric.java

@@ -5,7 +5,6 @@
  */
 package dan200.computercraft.core.apis.handles;
 
-import dan200.computercraft.api.lua.IArguments;
 import dan200.computercraft.api.lua.LuaException;
 import dan200.computercraft.api.lua.LuaFunction;
 import dan200.computercraft.shared.util.IoUtil;
@@ -15,6 +14,7 @@ import java.io.Closeable;
 import java.io.IOException;
 import java.nio.channels.Channel;
 import java.nio.channels.SeekableByteChannel;
+import java.util.Optional;
 
 public abstract class HandleGeneric
 {
@@ -39,6 +39,13 @@ public abstract class HandleGeneric
         closable = null;
     }
 
+    /**
+     * Close this file, freeing any resources it uses.
+     *
+     * Once a file is closed it may no longer be read or written to.
+     *
+     * @throws LuaException If the file has already been closed.
+     */
     @LuaFunction( "close" )
     public final void doClose() throws LuaException
     {
@@ -51,27 +58,27 @@ public abstract class HandleGeneric
      * Shared implementation for various file handle types.
      *
      * @param channel The channel to seek in
-     * @param args    The Lua arguments to process, like Lua's {@code file:seek}.
+     * @param whence  The seeking mode.
+     * @param offset  The offset to seek to.
      * @return The new position of the file, or null if some error occurred.
      * @throws LuaException If the arguments were invalid
      * @see <a href="https://www.lua.org/manual/5.1/manual.html#pdf-file:seek">{@code file:seek} in the Lua manual.</a>
      */
-    protected static Object[] handleSeek( SeekableByteChannel channel, IArguments args ) throws LuaException
+    protected static Object[] handleSeek( SeekableByteChannel channel, Optional<String> whence, Optional<Long> offset ) throws LuaException
     {
-        String whence = args.optString( 0, "cur" );
+        long actualOffset = offset.orElse( 0L );
-        long offset = args.optLong( 1, 0 );
         try
         {
-            switch( whence )
+            switch( whence.orElse( "cur" ) )
             {
                 case "set":
-                    channel.position( offset );
+                    channel.position( actualOffset );
                     break;
                 case "cur":
-                    channel.position( channel.position() + offset );
+                    channel.position( channel.position() + actualOffset );
                     break;
                 case "end":
-                    channel.position( channel.size() + offset );
+                    channel.position( channel.size() + actualOffset );
                     break;
                 default:
                     throw new LuaException( "bad argument #1 to 'seek' (invalid option '" + whence + "'" );
@@ -81,7 +88,7 @@ public abstract class HandleGeneric
         }
         catch( IllegalArgumentException e )
         {
-            return new Object[] { false, "Position is negative" };
+            return new Object[] { null, "Position is negative" };
         }
         catch( IOException e )
         {

src/main/java/dan200/computercraft/core/apis/http/request/HttpResponseHandle.java

@@ -5,7 +5,11 @@
  */
 package dan200.computercraft.core.apis.http.request;
 
+import dan200.computercraft.api.lua.IArguments;
 import dan200.computercraft.api.lua.LuaFunction;
+import dan200.computercraft.core.apis.HTTPAPI;
+import dan200.computercraft.core.apis.handles.BinaryReadableHandle;
+import dan200.computercraft.core.apis.handles.EncodedReadableHandle;
 import dan200.computercraft.core.apis.handles.HandleGeneric;
 import dan200.computercraft.core.asm.ObjectSource;
 
@@ -14,8 +18,12 @@ import java.util.Collections;
 import java.util.Map;
 
 /**
- * Wraps a {@link dan200.computercraft.core.apis.handles.HandleGeneric} and provides additional methods for
+ * A http response. This provides the same methods as a {@link EncodedReadableHandle file} (or
- * getting the response code and headers.
+ * {@link BinaryReadableHandle binary file} if the request used binary mode), though provides several request specific
+ * methods.
+ *
+ * @cc.module http.Response
+ * @see HTTPAPI#request(IArguments)  On how to make a http request.
  */
 public class HttpResponseHandle implements ObjectSource
 {
@@ -32,12 +40,37 @@ public class HttpResponseHandle implements ObjectSource
         this.responseHeaders = responseHeaders;
     }
 
+    /**
+     * Returns the response code and response message returned by the server.
+     *
+     * @return The response code and message.
+     * @cc.treturn number The response code (i.e. 200)
+     * @cc.treturn string The response message (i.e. "OK")
+     */
     @LuaFunction
     public final Object[] getResponseCode()
     {
         return new Object[] { responseCode, responseStatus };
     }
 
+    /**
+     * Get a table containing the response's headers, in a format similar to that required by {@link HTTPAPI#request}.
+     * If multiple headers are sent with the same name, they will be combined with a comma.
+     *
+     * @return The response's headers.
+     * @cc.usage Make a request to [example.computercraft.cc](https://example.computercraft.cc), and print the
+     * returned headers.
+     * <pre>{@code
+     * local request = http.get("https://example.computercraft.cc")
+     * print(textutils.serialize(request.getResponseHeaders()))
+     * -- => {
+     * --  [ "Content-Type" ] = "text/plain; charset=utf8",
+     * --  [ "content-length" ] = 17,
+     * --  ...
+     * -- }
+     * request.close()
+     * }</pre>
+     */
     @LuaFunction
     public final Map<String, String> getResponseHeaders()
     {

src/main/java/dan200/computercraft/core/terminal/Terminal.java

@@ -10,6 +10,8 @@ import dan200.computercraft.shared.util.Palette;
 import net.minecraft.nbt.CompoundNBT;
 import net.minecraft.network.PacketBuffer;
 
+import javax.annotation.Nonnull;
+
 public class Terminal
 {
     private static final String base16 = "0123456789abcdef";
@@ -29,7 +31,6 @@ public class Terminal
 
     private final Palette m_palette = new Palette();
 
-    private boolean m_changed = false;
     private final Runnable onChanged;
 
     public Terminal( int width, int height )
@@ -184,6 +185,7 @@ public class Terminal
         return m_cursorBackgroundColour;
     }
 
+    @Nonnull
     public Palette getPalette()
     {
         return m_palette;
@@ -305,15 +307,9 @@ public class Terminal
 
     public final void setChanged()
     {
-        m_changed = true;
         if( onChanged != null ) onChanged.run();
     }
 
-    public final void clearChanged()
-    {
-        m_changed = false;
-    }
-
     public synchronized void write( PacketBuffer buffer )
     {
         buffer.writeInt( m_cursorX );

src/main/java/dan200/computercraft/shared/common/ClientTerminal.java

@@ -25,10 +25,6 @@ public class ClientTerminal implements ITerminal
     {
         boolean changed = m_terminalChanged;
         m_terminalChanged = false;
-
-        Terminal terminal = m_terminal;
-        if( terminal != null ) terminal.clearChanged();
-
         return changed;
     }
 

src/main/java/dan200/computercraft/shared/common/ServerTerminal.java

@@ -58,9 +58,6 @@ public class ServerTerminal implements ITerminal
 
     public void update()
     {
-        Terminal terminal = m_terminal;
-        if( terminal != null ) terminal.clearChanged();
-
         m_terminalChangedLastFrame = m_terminalChanged.getAndSet( false );
     }
 

src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java

@@ -137,6 +137,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
      * @param computer The calling computer.
      * @param name     The peripheral's name.
      * @return A list of methods provided by this peripheral, or {@code nil} if it is not present.
+     * @cc.treturn { string... }|nil A list of methods provided by this peripheral, or {@code nil} if it is not present.
      * @see PeripheralAPI#getMethods
      */
     @LuaFunction

src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java

@@ -108,6 +108,8 @@ public class TurtleAPI implements ILuaAPI
      * Rotate the turtle 90 degress to the left.
      *
      * @return The turtle command result.
+     * @cc.treturn boolean Whether the turtle could successfully turn.
+     * @cc.treturn string|nil The reason the turtle could not turn.
      */
     @LuaFunction
     public final MethodResult turnLeft()
@@ -119,6 +121,8 @@ public class TurtleAPI implements ILuaAPI
      * Rotate the turtle 90 degress to the right.
      *
      * @return The turtle command result.
+     * @cc.treturn boolean Whether the turtle could successfully turn.
+     * @cc.treturn string|nil The reason the turtle could not turn.
      */
     @LuaFunction
     public final MethodResult turnRight()
@@ -279,6 +283,7 @@ public class TurtleAPI implements ILuaAPI
      * @param slot The slot to select.
      * @return The turtle command result.
      * @throws LuaException If the slot is out of range.
+     * @cc.treturn true When the slot has been selected.
      * @see #getSelectedSlot
      */
 
@@ -525,18 +530,39 @@ public class TurtleAPI implements ILuaAPI
         return trackCommand( new TurtleEquipCommand( TurtleSide.RIGHT ) );
     }
 
+    /**
+     * Get information about the block in front of the turtle.
+     *
+     * @return The turtle command result.
+     * @cc.treturn boolean Whether there is a block in front of the turtle.
+     * @cc.treturn table|string Information about the block in front, or a message explaining that there is no block.
+     */
     @LuaFunction
     public final MethodResult inspect()
     {
         return trackCommand( new TurtleInspectCommand( InteractDirection.FORWARD ) );
     }
 
+    /**
+     * Get information about the block above the turtle.
+     *
+     * @return The turtle command result.
+     * @cc.treturn boolean Whether there is a block above the turtle.
+     * @cc.treturn table|string Information about the above below, or a message explaining that there is no block.
+     */
     @LuaFunction
     public final MethodResult inspectUp()
     {
         return trackCommand( new TurtleInspectCommand( InteractDirection.UP ) );
     }
 
+    /**
+     * Get information about the block below the turtle.
+     *
+     * @return The turtle command result.
+     * @cc.treturn boolean Whether there is a block below the turtle.
+     * @cc.treturn table|string Information about the block below, or a message explaining that there is no block.
+     */
     @LuaFunction
     public final MethodResult inspectDown()
     {

src/main/java/dan200/computercraft/shared/turtle/core/TurtleDetectCommand.java

@@ -36,11 +36,8 @@ public class TurtleDetectCommand implements ITurtleCommand
         BlockPos oldPosition = turtle.getPosition();
         BlockPos newPosition = oldPosition.offset( direction );
 
-        if( !WorldUtil.isLiquidBlock( world, newPosition ) && !world.isAirBlock( newPosition ) )
+        return !WorldUtil.isLiquidBlock( world, newPosition ) && !world.isAirBlock( newPosition )
-        {
+            ? TurtleCommandResult.success()
-            return TurtleCommandResult.success();
+            : TurtleCommandResult.failure();
-        }
-
-        return TurtleCommandResult.failure();
     }
 }