1
0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2024-12-12 11:10:29 +00:00

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

Fix several documentation warnings
This commit is contained in:
Daniel Ratcliffe 2017-05-05 17:19:26 +01:00 committed by GitHub
commit 06b63980eb
30 changed files with 95 additions and 41 deletions

View File

@ -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 )

View File

@ -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;
}

View File

@ -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;
}

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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 );

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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)
*/

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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)

View File

@ -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.

View File

@ -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 );

View File

@ -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.

View File

@ -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();

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.