Some documentation bits and bobs

More #853, closes #858

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