mirrors/CC-Tweaked
1
0
Fork 0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2024-06-30 00:53:21 +00:00
Code Issues Releases Wiki Activity

Some documentation bits and bobs

Browse Source 
More #853, closes #858
This commit is contained in:
Jonathan Coates 2021-08-25 22:33:55 +01:00
parent 3396fe2871
commit 0f899357c2
No known key found for this signature in database
GPG Key ID: B9E431FF07C98D06
3 changed files with 73 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
src/main/java/dan200/computercraft/core/apis/OSAPI.java
View File

@ -204,15 +204,16 @@ public final void cancelTimer( int token )
}
/**
* Sets an alarm that will fire at the specified world time. When it fires,
* an {@code alarm} event will be added to the event queue with the ID
* returned from this function as the first parameter.
* Sets an alarm that will fire at the specified in-game time. When it
* fires, * an {@code alarm} event will be added to the event queue with the
* ID * returned from this function as the first parameter.
*
* @param time The time at which to fire the alarm, in the range [0.0, 24.0).
* @return The ID of the new alarm. This can be used to filter the
* {@code alarm} event, or {@link #cancelAlarm cancel the alarm}.
* @throws LuaException If the time is out of range.
* @see #cancelAlarm To cancel an alarm.
* @cc.since 1.2
*/
@LuaFunction
public final int setAlarm( double time ) throws LuaException
@ -233,6 +234,7 @@ public final int setAlarm( double time ) throws LuaException
*
* @param token The ID of the alarm to cancel.
* @see #setAlarm To set an alarm.
* @cc.since 1.2
*/
@LuaFunction
public final void cancelAlarm( int token )
@ -277,6 +279,7 @@ public final int getComputerID()
*
* @return The label of the computer.
* @cc.treturn string The label of the computer.
* @cc.since 1.3
*/
@LuaFunction( { "getComputerLabel", "computerLabel" } )
public final Object[] getComputerLabel()
@ -289,6 +292,7 @@ public final Object[] getComputerLabel()
* Set the label of this computer.
*
* @param label The new label. May be {@code nil} in order to clear it.
* @cc.since 1.3
*/
@LuaFunction
public final void setComputerLabel( Optional<String> label )
@ -300,6 +304,7 @@ public final void setComputerLabel( Optional<String> label )
* Returns the number of seconds that the computer has been running.
*
* @return The computer's uptime.
* @cc.since 1.2
*/
@LuaFunction
public final double clock()
@ -326,6 +331,14 @@ public final double clock()
* @throws LuaException If an invalid locale is passed.
* @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.
* @cc.see textutils.formatTime To convert times into a user-readable string.
* @cc.usage Print the current in-game time.
* <pre>{@code
* textutils.formatTime(os.time())
* }</pre>
* @cc.since 1.2
* @cc.changed 1.80pr1 Add support for getting the local local and UTC time.
* @cc.changed 1.83.0 {@link #time(IArguments)} now accepts table arguments and converts them to UNIX timestamps.
*/
@LuaFunction
public final Object time( IArguments args ) throws LuaException
@ -360,6 +373,7 @@ public final Object time( IArguments args ) throws LuaException
* @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.
* @cc.since 1.48
*/
@LuaFunction
public final int day( Optional<String> args ) throws LuaException
@ -390,6 +404,14 @@ public final int day( Optional<String> args ) throws LuaException
* @param args The locale to get the milliseconds for. Defaults to {@code ingame} if not set.
* @return The milliseconds since the epoch depending on the selected locale.
* @throws LuaException If an invalid locale is passed.
* @cc.since 1.80pr1
* @cc.usage Get the current time and use {@link #date} to convert it to a table.
* <pre>{@code
* -- Dividing by 1000 converts it from milliseconds to seconds.
* local time = os.epoch("local") / 1000
* local time_table = os.date("*t", time)
* print(textutils.serialize(time_table))
* }</pre>
*/
@LuaFunction
public final long epoch( Optional<String> args ) throws LuaException
@ -438,6 +460,11 @@ public final long epoch( Optional<String> args ) throws LuaException
* @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.
* @cc.since 1.83.0
* @cc.usage Print the current date in a user-friendly string.
* <pre>{@code
* os.date("%A %d %B %Y") -- See the reference above!
* }</pre>
*/
@LuaFunction
public final Object date( Optional<String> formatA, Optional<Long> timeA ) throws LuaException

7
src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
View File

@ -55,7 +55,12 @@ end
-- @tparam[opt] boolean bTwentyFourHour Whether to format this as a 24-hour
-- clock (`18:30`) rather than a 12-hour one (`6:30 AM`)
-- @treturn string The formatted time
-- @usage textutils.formatTime(os.time())
-- @usage Print the current in-game time as a 12-hour clock.
--
-- textutils.formatTime(os.time())
-- @usage Print the local time as a 24-hour clock.
--
-- textutils.formatTime(os.time("local"), true)
function formatTime(nTime, bTwentyFourHour)
expect(1, nTime, "number")
expect(2, bTwentyFourHour, "boolean", "nil")

55
src/main/resources/data/computercraft/lua/rom/apis/window.lua
View File

@ -52,24 +52,40 @@ local type = type
local string_rep = string.rep
local string_sub = string.sub
--- Returns a terminal object that is a space within the specified parent
-- terminal object. This can then be used (or even redirected to) in the same
-- manner as eg a wrapped monitor. Refer to @{term|the term API} for a list of
-- functions available to it.
--
-- @{term} itself may not be passed as the parent, though @{term.native} is
-- acceptable. Generally, @{term.current} or a wrapped monitor will be most
-- suitable, though windows may even have other windows assigned as their
-- parents.
--
-- @tparam term.Redirect parent The parent terminal redirect to draw to.
-- @tparam number nX The x coordinate this window is drawn at in the parent terminal
-- @tparam number nY The y coordinate this window is drawn at in the parent terminal
-- @tparam number nWidth The width of this window
-- @tparam number nHeight The height of this window
-- @tparam[opt] boolean bStartVisible Whether this window is visible by
-- default. Defaults to `true`.
-- @treturn Window The constructed window
--[[- Returns a terminal object that is a space within the specified parent
terminal object. This can then be used (or even redirected to) in the same
manner as eg a wrapped monitor. Refer to @{term|the term API} for a list of
functions available to it.
@{term} itself may not be passed as the parent, though @{term.native} is
acceptable. Generally, @{term.current} or a wrapped monitor will be most
suitable, though windows may even have other windows assigned as their
parents.
@tparam term.Redirect parent The parent terminal redirect to draw to.
@tparam number nX The x coordinate this window is drawn at in the parent terminal
@tparam number nY The y coordinate this window is drawn at in the parent terminal
@tparam number nWidth The width of this window
@tparam number nHeight The height of this window
@tparam[opt] boolean bStartVisible Whether this window is visible by
default. Defaults to `true`.
@treturn Window The constructed window
@since 1.6
@usage Create a smaller window, fill it red and write some text to it.
local my_window = window.create(term.current(), 1, 1, 20, 5)
my_window.setBackgroundColour(colours.red)
my_window.setTextColour(colours.white)
my_window.clear()
my_window.write("Testing my window!")
@usage Create a smaller window and redirect to it.
local my_window = window.create(term.current(), 1, 1, 25, 5)
term.redirect(my_window)
print("Writing some long text which will wrap around and show the bounds of this window.")
]]
function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
expect(1, parent, "table")
expect(2, nX, "number")
@ -446,6 +462,7 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
-- @treturn string The text colours of this line, suitable for use with @{term.blit}.
-- @treturn string The background colours of this line, suitable for use with @{term.blit}.
-- @throws If `y` is not between 1 and this window's height.
-- @since 1.84.0
function window.getLine(y)
if type(y) ~= "number" then expect(1, y, "number") end
@ -479,6 +496,7 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
--
-- @treturn boolean Whether this window is visible.
-- @see Window:setVisible
-- @since 1.94.0
function window.isVisible()
return bVisible
end
@ -525,6 +543,7 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
-- @tparam number new_height The new height of this window.
-- @tparam[opt] term.Redirect new_parent The new redirect object this
-- window should draw to.
-- @changed 1.85.0 Add `new_parent` parameter.
function window.reposition(new_x, new_y, new_width, new_height, new_parent)
if type(new_x) ~= "number" then expect(1, new_x, "number") end
if type(new_y) ~= "number" then expect(2, new_y, "number") end