From 826797cbd579e867f0f35f0be44b6a28c8c094a9 Mon Sep 17 00:00:00 2001
From: JackMacWindows <jackmacwindowslinux@gmail.com>
Date: Sun, 29 Nov 2020 06:24:18 -0500
Subject: [PATCH] Added documentation for global functions (#592)

---
 doc/stub/global.lua                           | 74 ++++++++++++++++++-
 .../shared/turtle/apis/TurtleAPI.java         |  2 +-
 2 files changed, 73 insertions(+), 3 deletions(-)

diff --git a/doc/stub/global.lua b/doc/stub/global.lua
index c0609a1c3..2c0f64ae1 100644
--- a/doc/stub/global.lua
+++ b/doc/stub/global.lua
@@ -1,6 +1,6 @@
 --[[-
-Global functions defined by `bios.lua`. This does not include standard Lua
-functions.
+Functions in the global environment, defined in `bios.lua`. This does not
+include standard Lua functions.
 
 @module _G
 ]]
@@ -27,18 +27,87 @@ or the @{parallel|parallel API}.
 nearest multiple of 0.05.
 
 @see os.startTimer
+@usage Sleep for three seconds.
+
+    print("Sleeping for three seconds")
+    sleep(3)
+    print("Done!")
 ]]
 function sleep(time) end
 
+--- Writes a line of text to the screen without a newline at the end, wrapping
+-- text if necessary.
+--
+-- @tparam string text The text to write to the string
+-- @treturn number The number of lines written
+-- @see print A wrapper around write that adds a newline and accepts multiple arguments
+-- @usage write("Hello, world")
 function write(text) end
+
+--- Prints the specified values to the screen separated by spaces, wrapping if
+-- necessary. After printing, the cursor is moved to the next line.
+--
+-- @param ... The values to print on the screen
+-- @treturn number The number of lines written
+-- @usage print("Hello, world!")
 function print(...) end
+
+--- Prints the specified values to the screen in red, separated by spaces,
+-- wrapping if necessary. After printing, the cursor is moved to the next line.
+--
+-- @param ... The values to print on the screen
+-- @usage printError("Something went wrong!")
 function printError(...) end
 
+--[[- Reads user input from the terminal, automatically handling arrow keys,
+pasting, character replacement, history scrollback, auto-completion, and
+default values.
+
+@tparam[opt] string replaceChar A character to replace each typed character with.
+This can be used for hiding passwords, for example.
+@tparam[opt] table history A table holding history items that can be scrolled
+back to with the up/down arrow keys. The oldest item is at index 1, while the
+newest item is at the highest index.
+@tparam[opt] function(partial: string):({ string... }|nil) completeFn A function
+to be used for completion. This function should take the partial text typed so
+far, and returns a list of possible completion options.
+@tparam[opt] string default Default text which should already be entered into
+the prompt.
+
+@treturn string The text typed in.
+
+@see cc.completion For functions to help with completion.
+@usage Read an string and echo it back to the user
+
+    write("> ")
+    local msg = read()
+    print(msg)
+
+@usage Prompt a user for a password.
+
+    while true do
+      write("Password> ")
+      local pwd = read("*")
+      if pwd == "let me in" then break end
+      print("Incorrect password, try again.")
+    end
+    print("Logged in!")
+
+@usage A complete example with completion, history and a default value.
+
+    local completion = require "cc.completion"
+    local history = { "potato", "orange", "apple" }
+    local choices = { "apple", "orange", "banana", "strawberry" }
+    write("> ")
+    local msg = read(nil, history, function(text) return completion.choice(text, choices) end, "app")
+    print(msg)
+]]
 function read(replaceChar, history, completeFn, default) end
 
 --- The ComputerCraft and Minecraft version of the current computer environment.
 --
 -- For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`.
+-- @usage _HOST
 _HOST = _HOST
 
 --[[- The default computer settings as defined in the ComputerCraft
@@ -51,5 +120,6 @@ An example value to disable autocompletion:
 
     shell.autocomplete=false,lua.autocomplete=false,edit.autocomplete=false
 
+@usage _CC_DEFAULT_SETTINGS
 ]]
 _CC_DEFAULT_SETTINGS = _CC_DEFAULT_SETTINGS
diff --git a/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java b/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
index 57040804c..b96e3f999 100644
--- a/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
+++ b/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
@@ -501,7 +501,7 @@ public final MethodResult transferTo( int slotArg, Optional<Integer> countArg )
     }
 
     /**
-     * Get the currently sleected slot.
+     * Get the currently selected slot.
      *
      * @return The current slot.
      * @see #select