Document several undocumented arguments and exceptions

src/main/java/dan200/computercraft/api/ComputerCraftAPI.java

@@ -123,8 +123,8 @@ public final class ComputerCraftAPI
      * resources with the same domain and path.
      *
      * @param modClass A class in whose jar to look first for the resources to mount. Using your main mod class is recommended. eg: MyMod.class
-     * @param domain   The domain under which to look for resources. eg: "mymod"
+     * @param domain   The domain under which to look for resources. eg: "mymod".
-     * @param subPath  The domain under which to look for resources. eg: "mymod/lua/myfiles"
+     * @param subPath  The domain under which to look for resources. eg: "mymod/lua/myfiles".
      * @return The mount, or {@code null} if it could be created for some reason. Use IComputerAccess.mount() or
      * IComputerAccess.mountWritable() to mount this on a Computers' file system.
      * @see IComputerAccess#mount(String, IMount)
@@ -148,6 +148,7 @@ public final class ComputerCraftAPI
     /**
      * Registers a peripheral handler to convert blocks into {@link IPeripheral} implementations.
      *
+     * @param handler The peripheral provider to register.
      * @see dan200.computercraft.api.peripheral.IPeripheral
      * @see dan200.computercraft.api.peripheral.IPeripheralProvider
      */
@@ -169,6 +170,7 @@ public final class ComputerCraftAPI
      * users should be able to craft Turtles with your new turtle. It is recommended to call
      * this during the load() method of your mod.
      *
+     * @param upgrade The turtle upgrade to register.
      * @see dan200.computercraft.api.turtle.ITurtleUpgrade
      */
     public static void registerTurtleUpgrade( ITurtleUpgrade upgrade )
@@ -188,8 +190,9 @@ public final class ComputerCraftAPI
     }
 
     /**
-     * Registers a bundled redstone handler to provide bundled redstone output for blocks
+     * Registers a bundled redstone handler to provide bundled redstone output for blocks.
      *
+     * @param handler The bundled redstone provider to register.
      * @see dan200.computercraft.api.redstone.IBundledRedstoneProvider
      */
     public static void registerBundledRedstoneProvider( IBundledRedstoneProvider handler )
@@ -208,6 +211,9 @@ public final class ComputerCraftAPI
     /**
      * If there is a Computer or Turtle at a certain position in the world, get it's bundled redstone output.
      *
+     * @param world The world this block is in.
+     * @param pos   The position this block is at.
+     * @param side  The side to extract the bundled redstone output from.
      * @return If there is a block capable of emitting bundled redstone at the location, it's signal (0-65535) will be returned.
      * If there is no block capable of emitting bundled redstone at the location, -1 will be returned.
      * @see dan200.computercraft.api.redstone.IBundledRedstoneProvider
@@ -229,6 +235,7 @@ public final class ComputerCraftAPI
     /**
      * Registers a media handler to provide {@link IMedia} implementations for Items
      *
+     * @param handler The media provider to register.
      * @see dan200.computercraft.api.media.IMediaProvider
      */
     public static void registerMediaProvider( IMediaProvider handler )
@@ -245,8 +252,9 @@ public final class ComputerCraftAPI
     }
 
     /**
-     * Registers a permission handler to restrict where turtles can move or build
+     * Registers a permission handler to restrict where turtles can move or build.
      *
+     * @param handler The turtle permission provider to register.
      * @see dan200.computercraft.api.permissions.ITurtlePermissionProvider
      */
     public static void registerPermissionProvider( ITurtlePermissionProvider handler )

src/main/java/dan200/computercraft/api/filesystem/IMount.java

@@ -34,6 +34,7 @@ public interface IMount
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram"
      * @return If the file exists.
+     * @throws IOException If an error occurs when checking the existence of the file.
      */
     public boolean exists( String path ) throws IOException;
 
@@ -42,6 +43,7 @@ public interface IMount
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprograms".
      * @return If the file exists and is a directory
+     * @throws IOException If an error occurs when checking whether the file is a directory.
      */
     public boolean isDirectory( String path ) throws IOException;
 
@@ -50,6 +52,7 @@ public interface IMount
      *
      * @param path     A file path in normalised format, relative to the mount location. ie: "programs/myprograms".
      * @param contents A list of strings. Add all the file names to this list.
+     * @throws IOException If the file was not a directory, or could not be listed.
      */
     public void list( String path, List<String> contents ) throws IOException;
 
@@ -58,6 +61,7 @@ public interface IMount
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
      * @return The size of the file, in bytes.
+     * @throws IOException If the file does not exist, or its size could not be determined.
      */
     public long getSize( String path ) throws IOException;
 
@@ -66,6 +70,7 @@ public interface IMount
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
      * @return A stream representing the contents of the file.
+     * @throws IOException If the file does not exist, or could not be opened.
      */
     public InputStream openForRead( String path ) throws IOException;
 }

src/main/java/dan200/computercraft/api/filesystem/IWritableMount.java

@@ -31,6 +31,7 @@ public interface IWritableMount extends IMount
      * Creates a directory at a given path inside the virtual file system.
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/mynewprograms".
+     * @throws IOException If the directory already exists or could not be created.
      */
     public void makeDirectory( String path ) throws IOException;
 
@@ -38,6 +39,7 @@ public interface IWritableMount extends IMount
      * Deletes a directory at a given path inside the virtual file system.
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/myoldprograms".
+     * @throws IOException If the file does not exist or could not be deleted.
      */
     public void delete( String path ) throws IOException;
 
@@ -45,7 +47,8 @@ public interface IWritableMount extends IMount
      * Opens a file with a given path, and returns an {@link OutputStream} for writing to it.
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
-     * @return a stream for writing to
+     * @return A stream for writing to
+     * @throws IOException If the file could not be opened for writing.
      */
     public OutputStream openForWrite( String path ) throws IOException;
 
@@ -54,6 +57,7 @@ public interface IWritableMount extends IMount
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
      * @return A stream for writing to.
+     * @throws IOException If the file could not be opened for writing.
      */
     public OutputStream openForAppend( String path ) throws IOException;
 
@@ -62,6 +66,7 @@ public interface IWritableMount extends IMount
      * mount, and write operations should fail once it reaches zero.
      *
      * @return The amount of free space, in bytes.
+     * @throws IOException If the remaining space could not be computed.
      */
     public long getRemainingSpace() throws IOException;
 }

src/main/java/dan200/computercraft/api/filesystem/package-info.java

@@ -1,4 +1,4 @@
-/**
+/*
  * This file is part of the public ComputerCraft API - http://www.computercraft.info
  * Copyright Daniel Ratcliffe, 2011-2016. This API may be redistributed unmodified and in full only.
  * For help using the API, and posting your mods, visit the forums at computercraft.info.

src/main/java/dan200/computercraft/api/lua/ILuaObject.java

@@ -21,6 +21,7 @@ public interface ILuaObject
      * Get the names of the methods that this object implements. This works the same as {@link IPeripheral#getMethodNames()}.
      * See that method for detailed documentation.
      *
+     * @return The method names this object provides.
      * @see IPeripheral#getMethodNames()
      */
     public String[] getMethodNames();
@@ -30,6 +31,16 @@ public interface ILuaObject
      * {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])}}. See that method for detailed
      * documentation.
      *
+     * @param context   The context of the currently running lua thread. This can be used to wait for events
+     *                  or otherwise yield.
+     * @param method    An integer identifying which of the methods from getMethodNames() the computercraft
+     *                  wishes to call. The integer indicates the index into the getMethodNames() table
+     *                  that corresponds to the string passed into peripheral.call()
+     * @param arguments The arguments for this method. See {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])}
+     *                  the possible values and conversion rules.
+     * @return An array of objects, representing the values you wish to return to the Lua program.
+     * See {@link IPeripheral#callMethod(IComputerAccess, ILuaContext, int, Object[])} for the valid values and
+     * conversion rules.
      * @throws LuaException         If the task could not be queued, or if the task threw an exception.
      * @throws InterruptedException If the user shuts down or reboots the computer the coroutine is suspended,
      *                              InterruptedException will be thrown. This exception must not be caught or

src/main/java/dan200/computercraft/api/media/IMediaProvider.java

@@ -18,7 +18,8 @@ public interface IMediaProvider
     /**
      * Produce an IMedia implementation from an ItemStack.
      *
-     * @return an IMedia implementation, or null if the item is not something you wish to handle
+     * @param stack The stack from which to extract the media information.
+     * @return An IMedia implementation, or null if the item is not something you wish to handle
      * @see dan200.computercraft.api.ComputerCraftAPI#registerMediaProvider(IMediaProvider)
      */
     public IMedia getMedia( ItemStack stack );

src/main/java/dan200/computercraft/api/peripheral/IPeripheralProvider.java

@@ -20,6 +20,9 @@ public interface IPeripheralProvider
     /**
      * Produce an peripheral implementation from a block location.
      *
+     * @param world The world the block is in.
+     * @param pos   The position the block is at.
+     * @param side  The side to get the peripheral from.
      * @return A peripheral, or {@code null} if there is not a peripheral here you'd like to handle.
      * @see dan200.computercraft.api.ComputerCraftAPI#registerPeripheralProvider(IPeripheralProvider)
      */

src/main/java/dan200/computercraft/api/redstone/IBundledRedstoneProvider.java

@@ -20,6 +20,9 @@ public interface IBundledRedstoneProvider
     /**
      * Produce an bundled redstone output from a block location.
      *
+     * @param world The world this block is in.
+     * @param pos   The position this block is at.
+     * @param side  The side to extract the bundled redstone output from.
      * @return A number in the range 0-65535 to indicate this block is providing output, or -1 if you do not wish to
      * handle this block.
      * @see dan200.computercraft.api.ComputerCraftAPI#registerBundledRedstoneProvider(IBundledRedstoneProvider)

src/main/java/dan200/computercraft/api/turtle/ITurtleAccess.java

@@ -112,7 +112,8 @@ public interface ITurtleAccess
     /**
      * Sets the colour of the turtle, as if the player had dyed it with a dye item.
      *
-     * @param dyeColour 0-15 to dye the turtle one of the 16 standard Minecraft colours, or -1 to remove the dye from the turtle.
+     * @param dyeColour 0-15 to dye the turtle one of the 16 standard Minecraft <em>dye</em> colours, or -1 to remove
+     *                  the dye from the turtle.
      * @see #getDyeColour()
      */
     public void setDyeColour( int dyeColour );
@@ -120,7 +121,8 @@ public interface ITurtleAccess
     /**
      * Gets the colour the turtle has been dyed.
      *
-     * @return 0-15 if the turtle has been dyed one of the 16 standard Minecraft colours, -1 if the turtle is clean.
+     * @return 0-15 if the turtle has been dyed one of the 16 standard Minecraft <em>dye</em> colours, -1 if the turtle
+     * is clean.
      * @see #getDyeColour()
      */
     public int getDyeColour();
@@ -194,11 +196,18 @@ public interface ITurtleAccess
      * be supplied as a parameter to a "turtle_response" event issued to the turtle after the command has completed. Look at the
      * lua source code for "rom/apis/turtle" for how to build a lua wrapper around this functionality.
      *
-     * @param command an object which will execute the custom command when its point in the queue is reached
+     * @param context The Lua context to pull events from.
-     * @return the objects the command returned when executed. you should probably return these to the player
+     * @param command An object which will execute the custom command when its point in the queue is reached
+     * @return The objects the command returned when executed. you should probably return these to the player
      * unchanged if called from a peripheral method.
      * @throws UnsupportedOperationException When attempting to execute a command on the client side.
+     * @throws LuaException                  If the user presses CTRL+T to terminate the current program while {@code executeCommand()} is
+     *                                       waiting for an event, a "Terminated" exception will be thrown here.
+     * @throws InterruptedException          If the user shuts down or reboots the computer while pullEvent() is waiting for an
+     *                                       event, InterruptedException will be thrown. This exception must not be caught or
+     *                                       intercepted, or the computer will leak memory and end up in a broken state.
      * @see ITurtleCommand
+     * @see ILuaContext#pullEvent(String)
      */
     public Object[] executeCommand( ILuaContext context, ITurtleCommand command ) throws LuaException, InterruptedException;
 
@@ -215,6 +224,7 @@ public interface ITurtleAccess
     /**
      * Returns the turtle on the specified side of the turtle, if there is one.
      *
+     * @param side The side to get the upgrade from.
      * @return The upgrade on the specified side of the turtle, if there is one.
      * @see #setUpgrade(TurtleSide, ITurtleUpgrade)
      */
@@ -232,6 +242,7 @@ public interface ITurtleAccess
     /**
      * Returns the peripheral created by the upgrade on the specified side of the turtle, if there is one.
      *
+     * @param side The side to get the peripheral from.
      * @return The peripheral created by the upgrade on the specified side of the turtle, {@code null} if none exists.
      */
     public IPeripheral getPeripheral( TurtleSide side );

src/main/java/dan200/computercraft/api/turtle/ITurtleUpgrade.java

@@ -33,6 +33,7 @@ public interface ITurtleUpgrade
      * You should use a unique resource domain to ensure this upgrade is uniquely identified.
      * The turtle will fail registration if an already used ID is specified.
      *
+     * @return The unique ID for this upgrade.
      * @see ComputerCraftAPI#registerTurtleUpgrade(ITurtleUpgrade)
      */
     public ResourceLocation getUpgradeID();
@@ -43,6 +44,7 @@ public interface ITurtleUpgrade
      * not released for older ComputerCraft versions, you can return -1 here.
      * The turtle will fail registration if an already used positive ID is specified.
      *
+     * @return The legacy ID, or -1 if is needed.
      * @see ComputerCraftAPI#registerTurtleUpgrade(ITurtleUpgrade)
      */
     public int getLegacyUpgradeID();
@@ -51,13 +53,16 @@ public interface ITurtleUpgrade
      * Return an unlocalised string to describe this type of turtle in turtle item names.
      *
      * Examples of built-in adjectives are "Wireless", "Mining" and "Crafty".
+     *
+     * @return The localisation key for this upgrade's adjective.
      */
     public String getUnlocalisedAdjective();
 
     /**
      * Return whether this turtle adds a tool or a peripheral to the turtle.
      *
-     * @see TurtleUpgradeType for the differences between the two.
+     * @return The type of upgrade this is.
+     * @see TurtleUpgradeType for the differences between them.
      */
     public TurtleUpgradeType getType();
 
@@ -65,6 +70,8 @@ public interface ITurtleUpgrade
      * Return an item stack representing the type of item that a turtle must be crafted
      * with to create a turtle which holds this upgrade. This item stack is also used
      * to determine the upgrade given by {@code turtle.equip()}
+     *
+     * @return The item stack to craft with, or {@code null} if it cannot be crafted.
      */
     public ItemStack getCraftingItem();