From 3075f89797c971e7a57214437ce82ddd0f9c8add Mon Sep 17 00:00:00 2001 From: JackMacWindows Date: Sun, 5 Jul 2020 03:26:37 -0400 Subject: [PATCH] Added Javadoc for currently undocumented functions (#490) This PR adds some documentation for APIs that did not have docs in the source yet. This includes the: * drive peripheral * FS API * OS PAI * printer peripheral * speaker peripheral --- .../dan200/computercraft/core/apis/FSAPI.java | 132 ++++++++++++++++++ .../dan200/computercraft/core/apis/OSAPI.java | 131 +++++++++++++++++ .../diskdrive/DiskDrivePeripheral.java | 64 +++++++++ .../peripheral/printer/PrinterPeripheral.java | 57 ++++++++ .../peripheral/speaker/SpeakerPeripheral.java | 31 ++++ 5 files changed, 415 insertions(+) diff --git a/src/main/java/dan200/computercraft/core/apis/FSAPI.java b/src/main/java/dan200/computercraft/core/apis/FSAPI.java index 288f93636..fc909c683 100644 --- a/src/main/java/dan200/computercraft/core/apis/FSAPI.java +++ b/src/main/java/dan200/computercraft/core/apis/FSAPI.java @@ -61,6 +61,13 @@ public class FSAPI implements ILuaAPI fileSystem = null; } + /** + * Returns a list of files in a directory. + * + * @param path The path to list. + * @return A table with a list of files in the directory. + * @throws LuaException If the path doesn't exist. + */ @LuaFunction public final String[] list( String path ) throws LuaException { @@ -75,24 +82,51 @@ public class FSAPI implements ILuaAPI } } + /** + * Combines two parts of a path into one full path, adding separators as + * needed. + * + * @param pathA The first part of the path. For example, a parent directory path. + * @param pathB The second part of the path. For example, a file name. + * @return The new path, with separators added between parts as needed. + */ @LuaFunction public final String combine( String pathA, String pathB ) { return fileSystem.combine( pathA, pathB ); } + /** + * Returns the file name portion of a path. + * + * @param path The path to get the name from. + * @return The final part of the path (the file name). + */ @LuaFunction public final String getName( String path ) { return FileSystem.getName( path ); } + /** + * Returns the parent directory portion of a path. + * + * @param path The path to get the directory from. + * @return The path with the final part removed (the parent directory). + */ @LuaFunction public final String getDir( String path ) { return FileSystem.getDirectory( path ); } + /** + * Returns the size of the specified file. + * + * @param path The file to get the file size of. + * @return The size of the file, in bytes. + * @throws LuaException If the path doesn't exist. + */ @LuaFunction public final long getSize( String path ) throws LuaException { @@ -106,6 +140,12 @@ public class FSAPI implements ILuaAPI } } + /** + * Returns whether the specified path exists. + * + * @param path The path to check the existence of. + * @return Whether the path exists. + */ @LuaFunction public final boolean exists( String path ) { @@ -119,6 +159,12 @@ public class FSAPI implements ILuaAPI } } + /** + * Returns whether the specified path is a directory. + * + * @param path The path to check. + * @return Whether the path is a directory. + */ @LuaFunction public final boolean isDir( String path ) { @@ -132,6 +178,12 @@ public class FSAPI implements ILuaAPI } } + /** + * Returns whether a path is read-only. + * + * @param path The path to check. + * @return Whether the path cannot be written to. + */ @LuaFunction public final boolean isReadOnly( String path ) { @@ -145,6 +197,12 @@ public class FSAPI implements ILuaAPI } } + /** + * Creates a directory, and any missing parents, at the specified path. + * + * @param path The path to the directory to create. + * @throws LuaException If the directory couldn't be created. + */ @LuaFunction public final void makeDir( String path ) throws LuaException { @@ -159,6 +217,15 @@ public class FSAPI implements ILuaAPI } } + /** + * Moves a file or directory from one path to another. + * + * Any parent directories are created as needed. + * + * @param path The current file or directory to move from. + * @param dest The destination path for the file or directory. + * @throws LuaException If the file or directory couldn't be moved. + */ @LuaFunction public final void move( String path, String dest ) throws LuaException { @@ -173,6 +240,15 @@ public class FSAPI implements ILuaAPI } } + /** + * Copies a file or directory to a new path. + * + * Any parent directories are created as needed. + * + * @param path The file or directory to copy. + * @param dest The path to the destination file or directory. + * @throws LuaException If the file or directory couldn't be copied. + */ @LuaFunction public final void copy( String path, String dest ) throws LuaException { @@ -187,6 +263,15 @@ public class FSAPI implements ILuaAPI } } + /** + * Deletes a file or directory. + * + * If the path points to a directory, all of the enclosed files and + * subdirectories are also deleted. + * + * @param path The path to the file or directory to delete. + * @throws LuaException If the file or directory couldn't be deleted. + */ @LuaFunction public final void delete( String path ) throws LuaException { @@ -201,6 +286,24 @@ public class FSAPI implements ILuaAPI } } + // FIXME: Add individual handle type documentation + + /** + * Opens a file for reading or writing at a path. + * + * The mode parameter can be {@code r} to read, {@code w} to write (deleting + * all contents), or {@code a} to append (keeping contents). If {@code b} is + * added to the end, the file will be opened in binary mode; otherwise, it's + * opened in text mode. + * + * @param path The path to the file to open. + * @param mode The mode to open the file with. + * @return A file handle object for the file, or {@code nil} + an error message on error. + * @throws LuaException If an invalid mode was specified. + * @cc.treturn [1] table A file handle object for the file. + * @cc.treturn [2] nil If the file does not exist, or cannot be opened. + * @cc.treturn string|nil A message explaining why the file cannot be opened. + */ @LuaFunction public final Object[] open( String path, String mode ) throws LuaException { @@ -255,6 +358,14 @@ public class FSAPI implements ILuaAPI } } + /** + * Returns the name of the mount that the specified path is located on. + * + * @param path The path to get the drive of. + * @return The name of the drive that the file is on; e.g. {@code hdd} for local files, or {@code rom} for ROM files. + * @throws LuaException If the path doesn't exist. + * @cc.treturn string The name of the drive that the file is on; e.g. {@code hdd} for local files, or {@code rom} for ROM files. + */ @LuaFunction public final Object[] getDrive( String path ) throws LuaException { @@ -268,6 +379,15 @@ public class FSAPI implements ILuaAPI } } + /** + * Returns the amount of free space available on the drive the path is + * located on. + * + * @param path The path to check the free space for. + * @return The amount of free space available, in bytes. + * @cc.treturn number|"unlimited" The amount of free space available, in bytes, or "unlimited". + * @throws LuaException If the path doesn't exist. + */ @LuaFunction public final Object getFreeSpace( String path ) throws LuaException { @@ -282,6 +402,18 @@ public class FSAPI implements ILuaAPI } } + /** + * Searches for files matching a string with wildcards. + * + * This string is formatted like a normal path string, but can include any + * number of wildcards ({@code *}) to look for files matching anything. + * For example, {@code rom/* /command*} will look for any path starting with + * {@code command} inside any subdirectory of {@code /rom}. + * + * @param path The wildcard-qualified path to search for. + * @return A list of paths that match the search string. + * @throws LuaException If the path doesn't exist. + */ @LuaFunction public final String[] find( String path ) throws LuaException { diff --git a/src/main/java/dan200/computercraft/core/apis/OSAPI.java b/src/main/java/dan200/computercraft/core/apis/OSAPI.java index 34ee37853..43a5c473f 100644 --- a/src/main/java/dan200/computercraft/core/apis/OSAPI.java +++ b/src/main/java/dan200/computercraft/core/apis/OSAPI.java @@ -153,24 +153,58 @@ public class OSAPI implements ILuaAPI return c.getTime().getTime(); } + /** + * Adds an event to the event queue. This event can later be pulled with + * os.pullEvent. + * + * @param name The name of the event to queue. + * @param args The parameters of the event. + * @cc.tparam string name The name of the event to queue. + * @cc.param ... The parameters of the event. + * @cc.see os.pullEvent To pull the event queued + */ @LuaFunction public final void queueEvent( String name, IArguments args ) { apiEnvironment.queueEvent( name, args.drop( 1 ).getAll() ); } + /** + * Starts a timer that will run for the specified number of seconds. Once + * the timer fires, a timer event will be added to the queue with the ID + * returned from this function as the first parameter. + * + * @param timer The number of seconds until the timer fires. + * @return The ID of the new timer. + * @throws LuaException If the time is below zero. + */ @LuaFunction public final int startTimer( double timer ) throws LuaException { return apiEnvironment.startTimer( Math.round( checkFinite( 0, timer ) / 0.05 ) ); } + /** + * Cancels a timer previously started with startTimer. This will stop the + * timer from firing. + * + * @param token The ID of the timer to cancel. + * @see #startTimer To start a timer. + */ @LuaFunction public final void cancelTimer( int token ) { apiEnvironment.cancelTimer( token ); } + /** + * Sets an alarm that will fire at the specified world time. When it fires, + * an alarm event will be added to the event queue. + * + * @param time The time at which to fire the alarm, in the range [0.0, 24.0). + * @return The ID of the alarm that was set. + * @throws LuaException If the time is out of range. + */ @LuaFunction public final int setAlarm( double time ) throws LuaException { @@ -184,6 +218,13 @@ public class OSAPI implements ILuaAPI } } + /** + * Cancels an alarm previously started with setAlarm. This will stop the + * alarm from firing. + * + * @param token The ID of the alarm to cancel. + * @see #setAlarm To set an alarm. + */ @LuaFunction public final void cancelAlarm( int token ) { @@ -193,24 +234,41 @@ public class OSAPI implements ILuaAPI } } + /** + * Shuts down the computer immediately. + */ @LuaFunction( "shutdown" ) public final void doShutdown() { apiEnvironment.shutdown(); } + /** + * Reboots the computer immediately. + */ @LuaFunction( "reboot" ) public final void doReboot() { apiEnvironment.reboot(); } + /** + * Returns the ID of the computer. + * + * @return The ID of the computer. + */ @LuaFunction( { "getComputerID", "computerID" } ) public final int getComputerID() { return apiEnvironment.getComputerID(); } + /** + * Returns the label of the computer, or {@code nil} if none is set. + * + * @return The label of the computer. + * @cc.treturn string The label of the computer. + */ @LuaFunction( { "getComputerLabel", "computerLabel" } ) public final Object[] getComputerLabel() { @@ -229,12 +287,37 @@ public class OSAPI implements ILuaAPI apiEnvironment.setLabel( StringUtil.normaliseLabel( label.orElse( null ) ) ); } + /** + * Returns the number of seconds that the computer has been running. + * + * @return The computer's uptime. + */ @LuaFunction public final double clock() { return m_clock * 0.05; } + /** + * Returns the current time depending on the string passed in. This will + * always be in the range [0.0, 24.0). + * + * * If called with {@code ingame}, the current world time will be returned. + * This is the default if nothing is passed. + * * If called with {@code utc}, returns the hour of the day in UTC time. + * * If called with {@code local}, returns the hour of the day in the + * timezone the server is located in. + * + * This function can also be called with a table returned from {@link #date}, + * which will convert the date fields into a UNIX timestamp (number of + * seconds since 1 January 1970). + * + * @param args The locale of the time, or a table filled by {@code os.date("*t")} to decode. Defaults to {@code ingame} locale if not specified. + * @return The hour of the selected locale, or a UNIX timestamp from the table, depending on the argument passed in. + * @cc.tparam [opt] string|table locale The locale of the time, or a table filled by {@code os.date("*t")} to decode. Defaults to {@code ingame} locale if not specified. + * @see #date To get a date table that can be converted with this function. + * @throws LuaException If an invalid locale is passed. + */ @LuaFunction public final Object time( IArguments args ) throws LuaException { @@ -255,6 +338,20 @@ public class OSAPI implements ILuaAPI } } + /** + * Returns the day depending on the locale specified. + * + * * If called with {@code ingame}, returns the number of days since the + * world was created. This is the default. + * * If called with {@code utc}, returns the number of days since 1 January + * 1970 in the UTC timezone. + * * If called with {@code local}, returns the number of days since 1 + * January 1970 in the server's local timezone. + * + * @param args The locale to get the day for. Defaults to {@code ingame} if not set. + * @return The day depending on the selected locale. + * @throws LuaException If an invalid locale is passed. + */ @LuaFunction public final int day( Optional args ) throws LuaException { @@ -271,6 +368,20 @@ public class OSAPI implements ILuaAPI } } + /** + * Returns the number of seconds since an epoch depending on the locale. + * + * * If called with {@code ingame}, returns the number of seconds since the + * world was created. This is the default. + * * If called with {@code utc}, returns the number of seconds since 1 + * January 1970 in the UTC timezone. + * * If called with {@code local}, returns the number of seconds since 1 + * January 1970 in the server's local timezone. + * + * @param args The locale to get the seconds for. Defaults to {@code ingame} if not set. + * @return The seconds since the epoch depending on the selected locale. + * @throws LuaException If an invalid locale is passed. + */ @LuaFunction public final long epoch( Optional args ) throws LuaException { @@ -299,6 +410,26 @@ public class OSAPI implements ILuaAPI } } + /** + * Returns a date string (or table) using a specified format string and + * optional time to format. + * + * The format string takes the same formats as C's {@code strftime} function + * (http://www.cplusplus.com/reference/ctime/strftime/). In extension, it + * can be prefixed with an exclamation mark ({@code !}) to use UTC time + * instead of the server's local timezone. + * + * If the format is exactly {@code *t} (optionally prefixed with {@code !}), a + * table will be returned instead. This table has fields for the year, month, + * day, hour, minute, second, day of the week, day of the year, and whether + * Daylight Savings Time is in effect. This table can be converted to a UNIX + * timestamp (days since 1 January 1970) with {@link #date}. + * + * @param formatA The format of the string to return. This defaults to {@code %c}, which expands to a string similar to "Sat Dec 24 16:58:00 2011". + * @param timeA The time to convert to a string. This defaults to the current time. + * @return The resulting format string. + * @throws LuaException If an invalid format is passed. + */ @LuaFunction public final Object date( Optional formatA, Optional timeA ) throws LuaException { diff --git a/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java index 8367e1f8b..dd15192db 100644 --- a/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java +++ b/src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java @@ -16,6 +16,7 @@ import dan200.computercraft.shared.util.StringUtil; import net.minecraft.item.ItemStack; import javax.annotation.Nonnull; +import javax.annotation.Nullable; import java.util.Optional; /** @@ -47,12 +48,23 @@ public class DiskDrivePeripheral implements IPeripheral return "drive"; } + /** + * Returns whether a disk is currently inserted in the drive. + * + * @return Whether a disk is currently inserted in the drive. + */ @LuaFunction public final boolean isDiskPresent() { return !diskDrive.getDiskStack().isEmpty(); } + /** + * Returns the label of the disk in the drive if available. + * + * @return The label of the disk, or {@code nil} if either no disk is inserted or the disk doesn't have a label. + * @cc.treturn string The label of the disk, or {@code nil} if either no disk is inserted or the disk doesn't have a label. + */ @LuaFunction public final Object[] getDiskLabel() { @@ -61,6 +73,17 @@ public class DiskDrivePeripheral implements IPeripheral return media == null ? null : new Object[] { media.getLabel( stack ) }; } + /** + * Sets or clears the label for a disk. + * + * If no label or {@code nil} is passed, the label will be cleared. + * + * If the inserted disk's label can't be changed (for example, a record), + * an error will be thrown. + * + * @param labelA The new label of the disk, or {@code nil} to clear. + * @throws LuaException If the disk's label can't be changed. + */ @LuaFunction( mainThread = true ) public final void setDiskLabel( Optional labelA ) throws LuaException { @@ -76,18 +99,36 @@ public class DiskDrivePeripheral implements IPeripheral diskDrive.setDiskStack( stack ); } + /** + * Returns whether a disk with data is inserted. + * + * @param computer The computer object + * @return Whether a disk with data is inserted. + */ @LuaFunction public final boolean hasData( IComputerAccess computer ) { return diskDrive.getDiskMountPath( computer ) != null; } + /** + * Returns the mount path for the inserted disk. + * + * @param computer The computer object + * @return The mount path for the disk, or {@code nil} if no data disk is inserted. + */ @LuaFunction + @Nullable public final String getMountPath( IComputerAccess computer ) { return diskDrive.getDiskMountPath( computer ); } + /** + * Returns whether a disk with audio is inserted. + * + * @return Whether a disk with audio is inserted. + */ @LuaFunction public final boolean hasAudio() { @@ -96,7 +137,13 @@ public class DiskDrivePeripheral implements IPeripheral return media != null && media.getAudio( stack ) != null; } + /** + * Returns the title of the inserted audio disk. + * + * @return The title of the audio, or {@code nil} if no audio disk is inserted. + */ @LuaFunction + @Nullable public final Object getAudioTitle() { ItemStack stack = diskDrive.getDiskStack(); @@ -104,24 +151,41 @@ public class DiskDrivePeripheral implements IPeripheral return media != null ? media.getAudioTitle( stack ) : false; } + /** + * Plays the audio in the inserted disk, if available. + */ @LuaFunction public final void playAudio() { diskDrive.playDiskAudio(); } + /** + * Stops any audio that may be playing. + * + * @see #playAudio + */ @LuaFunction public final void stopAudio() { diskDrive.stopDiskAudio(); } + /** + * Ejects any disk that may be in the drive. + */ @LuaFunction public final void ejectDisk() { diskDrive.ejectDisk(); } + /** + * Returns the ID of the disk inserted in the drive. + * + * @return The ID of the disk in the drive, or {@code nil} if no disk with an ID is inserted. + * @cc.treturn number The The ID of the disk in the drive, or {@code nil} if no disk with an ID is inserted. + */ @LuaFunction public final Object[] getDiskID() { diff --git a/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java index 5235e127c..6e7da2aad 100644 --- a/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java +++ b/src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java @@ -42,6 +42,13 @@ public class PrinterPeripheral implements IPeripheral // FIXME: None of our page modification functions actually mark the tile as dirty, so the page may not be // persisted correctly. + /** + * Writes text to the current page. + * + * @param arguments The values to write to the page. + * @cc.tparam string|number ... The values to write to the page. + * @throws LuaException If any values couldn't be converted to a string, or if no page is started. + */ @LuaFunction public final void write( IArguments arguments ) throws LuaException { @@ -51,6 +58,14 @@ public class PrinterPeripheral implements IPeripheral page.setCursorPos( page.getCursorX() + text.length(), page.getCursorY() ); } + /** + * Returns the current position of the cursor on the page. + * + * @return The position of the cursor. + * @cc.treturn number The X position of the cursor. + * @cc.treturn number The Y position of the cursor. + * @throws LuaException If a page isn't being printed. + */ @LuaFunction public final Object[] getCursorPos() throws LuaException { @@ -60,6 +75,13 @@ public class PrinterPeripheral implements IPeripheral return new Object[] { x + 1, y + 1 }; } + /** + * Sets the position of the cursor on the page. + * + * @param x The X coordinate to set the cursor at. + * @param y The Y coordinate to set the cursor at. + * @throws LuaException If a page isn't being printed. + */ @LuaFunction public final void setCursorPos( int x, int y ) throws LuaException { @@ -67,6 +89,14 @@ public class PrinterPeripheral implements IPeripheral page.setCursorPos( x - 1, y - 1 ); } + /** + * Returns the size of the current page. + * + * @return The size of the page. + * @cc.treturn number The width of the page. + * @cc.treturn number The height of the page. + * @throws LuaException If a page isn't being printed. + */ @LuaFunction public final Object[] getPageSize() throws LuaException { @@ -76,12 +106,23 @@ public class PrinterPeripheral implements IPeripheral return new Object[] { width, height }; } + /** + * Starts printing a new page. + * + * @return Whether a new page could be started. + */ @LuaFunction( mainThread = true ) public final boolean newPage() { return printer.startNewPage(); } + /** + * Finalizes printing of the current page and outputs it to the tray. + * + * @return Whether the page could be successfully finished. + * @throws LuaException If a page isn't being printed. + */ @LuaFunction( mainThread = true ) public final boolean endPage() throws LuaException { @@ -89,6 +130,12 @@ public class PrinterPeripheral implements IPeripheral return printer.endCurrentPage(); } + /** + * Sets the title of the current page. + * + * @param title The title to set for the page. + * @throws LuaException If a page isn't being printed. + */ @LuaFunction public final void setPageTitle( Optional title ) throws LuaException { @@ -96,12 +143,22 @@ public class PrinterPeripheral implements IPeripheral printer.setPageTitle( StringUtil.normaliseLabel( title.orElse( "" ) ) ); } + /** + * Returns the amount of ink left in the printer. + * + * @return The amount of ink available to print with. + */ @LuaFunction public final int getInkLevel() { return printer.getInkLevel(); } + /** + * Returns the amount of paper left in the printer. + * + * @return The amount of paper available to print with. + */ @LuaFunction public final int getPaperLevel() { diff --git a/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java b/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java index c1c5527e7..217b5b59f 100644 --- a/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java +++ b/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java @@ -58,6 +58,20 @@ public abstract class SpeakerPeripheral implements IPeripheral return "speaker"; } + /** + * Plays a sound through the speaker. + * + * This plays sounds similar to the {@code /playsound} command in Minecraft. + * It takes the namespaced path of a sound (e.g. {@code minecraft:block.note_block.harp}) + * with an optional volume and speed multiplier, and plays it through the speaker. + * + * @param context The Lua context + * @param name The name of the sound to play. + * @param volumeA The volume to play the sound at, from 0.0 to 3.0. Defaults to 1.0. + * @param pitchA The speed to play the sound at, from 0.5 to 2.0. Defaults to 1.0. + * @return Whether the sound could be played. + * @throws LuaException If the sound name couldn't be decoded. + */ @LuaFunction public final boolean playSound( ILuaContext context, String name, Optional volumeA, Optional pitchA ) throws LuaException { @@ -77,6 +91,23 @@ public abstract class SpeakerPeripheral implements IPeripheral return playSound( context, identifier, volume, pitch, false ); } + /** + * Plays a note block note through the speaker. + * + * This takes the name of a note to play, as well as optionally the volume + * and pitch to play the note at. + * + * The pitch argument uses semitones as the unit. This directly maps to the + * number of clicks on a note block. For reference, 0, 12, and 24 map to F#, + * and 6 and 18 map to C. + * + * @param context The Lua context + * @param name The name of the note to play. + * @param volumeA The volume to play the note at, from 0.0 to 3.0. Defaults to 1.0. + * @param pitchA The pitch to play the note at in semitones, from 0 to 24. Defaults to 12. + * @return Whether the note could be played. + * @throws LuaException If the instrument doesn't exist. + */ @LuaFunction public final synchronized boolean playNote( ILuaContext context, String name, Optional volumeA, Optional pitchA ) throws LuaException {