Some documentation bits and bobs

More #853, closes #858

src/main/java/dan200/computercraft/core/apis/OSAPI.java

@@ -204,15 +204,16 @@ public class OSAPI implements ILuaAPI
     }
 
     /**
-     * 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 class OSAPI implements ILuaAPI
      *
      * @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 class OSAPI implements ILuaAPI
      *
      * @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 class OSAPI implements ILuaAPI
      * 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 class OSAPI implements ILuaAPI
      * 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 class OSAPI implements ILuaAPI
      * @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 class OSAPI implements ILuaAPI
      * @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 class OSAPI implements ILuaAPI
      * @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 class OSAPI implements ILuaAPI
      * @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

src/main/resources/data/computercraft/lua/rom/apis/textutils.lua

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

src/main/resources/data/computercraft/lua/rom/apis/window.lua

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