Merge pull request #196 from SquidDev-CC/feature/docs

Fix several documentation warnings
2025-10-31 13:42:59 +00:00 · 2017-05-05 17:19:26 +01:00
parent 3eae944923 0cdd0ea21a
commit 06b63980eb
30 changed files with 95 additions and 41 deletions
--- a/src/main/java/dan200/computercraft/api/ComputerCraftAPI.java
+++ b/src/main/java/dan200/computercraft/api/ComputerCraftAPI.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.
@@ -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 subPath  The domain under which to look for resources. eg: "mymod/lua/myfiles"
+     * @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".
     * @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 )
--- a/src/main/java/dan200/computercraft/api/filesystem/IMount.java
+++ b/src/main/java/dan200/computercraft/api/filesystem/IMount.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.
@@ -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;
 }
--- a/src/main/java/dan200/computercraft/api/filesystem/IWritableMount.java
+++ b/src/main/java/dan200/computercraft/api/filesystem/IWritableMount.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.
@@ -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;
 }
--- a/src/main/java/dan200/computercraft/api/filesystem/package-info.java
+++ b/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.
--- a/src/main/java/dan200/computercraft/api/lua/ILuaContext.java
+++ b/src/main/java/dan200/computercraft/api/lua/ILuaContext.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.
--- a/src/main/java/dan200/computercraft/api/lua/ILuaObject.java
+++ b/src/main/java/dan200/computercraft/api/lua/ILuaObject.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.
@@ -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
--- a/src/main/java/dan200/computercraft/api/lua/ILuaTask.java
+++ b/src/main/java/dan200/computercraft/api/lua/ILuaTask.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.
--- a/src/main/java/dan200/computercraft/api/lua/LuaException.java
+++ b/src/main/java/dan200/computercraft/api/lua/LuaException.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.
--- a/src/main/java/dan200/computercraft/api/lua/package-info.java
+++ b/src/main/java/dan200/computercraft/api/lua/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.
--- a/src/main/java/dan200/computercraft/api/media/IMedia.java
+++ b/src/main/java/dan200/computercraft/api/media/IMedia.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.
--- a/src/main/java/dan200/computercraft/api/media/IMediaProvider.java
+++ b/src/main/java/dan200/computercraft/api/media/IMediaProvider.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.
@@ -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 );
--- a/src/main/java/dan200/computercraft/api/media/package-info.java
+++ b/src/main/java/dan200/computercraft/api/media/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.
--- a/src/main/java/dan200/computercraft/api/package-info.java
+++ b/src/main/java/dan200/computercraft/api/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.
--- a/src/main/java/dan200/computercraft/api/peripheral/IComputerAccess.java
+++ b/src/main/java/dan200/computercraft/api/peripheral/IComputerAccess.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.
--- a/src/main/java/dan200/computercraft/api/peripheral/IPeripheral.java
+++ b/src/main/java/dan200/computercraft/api/peripheral/IPeripheral.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.
--- a/src/main/java/dan200/computercraft/api/peripheral/IPeripheralProvider.java
+++ b/src/main/java/dan200/computercraft/api/peripheral/IPeripheralProvider.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.
@@ -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)
     */
--- a/src/main/java/dan200/computercraft/api/peripheral/package-info.java
+++ b/src/main/java/dan200/computercraft/api/peripheral/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.
--- a/src/main/java/dan200/computercraft/api/permissions/ITurtlePermissionProvider.java
+++ b/src/main/java/dan200/computercraft/api/permissions/ITurtlePermissionProvider.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.
--- a/src/main/java/dan200/computercraft/api/permissions/package-info.java
+++ b/src/main/java/dan200/computercraft/api/permissions/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.
--- a/src/main/java/dan200/computercraft/api/redstone/IBundledRedstoneProvider.java
+++ b/src/main/java/dan200/computercraft/api/redstone/IBundledRedstoneProvider.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.
@@ -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)
--- a/src/main/java/dan200/computercraft/api/redstone/package-info.java
+++ b/src/main/java/dan200/computercraft/api/redstone/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.
--- a/src/main/java/dan200/computercraft/api/turtle/ITurtleAccess.java
+++ b/src/main/java/dan200/computercraft/api/turtle/ITurtleAccess.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.
@@ -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
-     * @return the objects the command returned when executed. you should probably return these to the player
+     * @param context The Lua context to pull events from.
+     * @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 );
--- a/src/main/java/dan200/computercraft/api/turtle/ITurtleCommand.java
+++ b/src/main/java/dan200/computercraft/api/turtle/ITurtleCommand.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.
--- a/src/main/java/dan200/computercraft/api/turtle/ITurtleUpgrade.java
+++ b/src/main/java/dan200/computercraft/api/turtle/ITurtleUpgrade.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.
@@ -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();

--- a/src/main/java/dan200/computercraft/api/turtle/TurtleAnimation.java
+++ b/src/main/java/dan200/computercraft/api/turtle/TurtleAnimation.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.
--- a/src/main/java/dan200/computercraft/api/turtle/TurtleCommandResult.java
+++ b/src/main/java/dan200/computercraft/api/turtle/TurtleCommandResult.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.
--- a/src/main/java/dan200/computercraft/api/turtle/TurtleSide.java
+++ b/src/main/java/dan200/computercraft/api/turtle/TurtleSide.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.
--- a/src/main/java/dan200/computercraft/api/turtle/TurtleUpgradeType.java
+++ b/src/main/java/dan200/computercraft/api/turtle/TurtleUpgradeType.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.
--- a/src/main/java/dan200/computercraft/api/turtle/TurtleVerb.java
+++ b/src/main/java/dan200/computercraft/api/turtle/TurtleVerb.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.
--- a/src/main/java/dan200/computercraft/api/turtle/package-info.java
+++ b/src/main/java/dan200/computercraft/api/turtle/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.