moar docs.

docs/4-reference.markdown

@@ -101,6 +101,9 @@ doing if you use anything other than `:auto`.
 Terminals
 ---------
 
+The terminal layer is the lowest-level layer.  Read the [terminal
+documentation](../terminals/) for an overview.
+
 ### lanterna.terminal/get-terminal
 
     :::clojure
@@ -113,7 +116,7 @@ Get a terminal object.
 `kind` is a [console constant](#consoles) describing the type of terminal you
 want.  If unspecified it defaults to `:auto`.
 
-Options can contain one or more of the following mappings:
+The `options` map can contain any of the following mappings:
 
 * `:cols` - Width of the desired terminal in characters (default `80`).
 * `:rows` - Height of the desired terminal in characters (default `24`).
@@ -303,13 +306,176 @@ when you call [`get-terminal`](#lanternaterminalget-terminal).  It's here if you
 Screens
 -------
 
+The screen layer is an abstraction that provides buffering on top of the
+terminal layer.  Read the [screen documentation](../screens/) for an overview.
+
 ### lanterna.screen/get-screen
+
+    :::clojure
+    (get-screen)
+    (get-screen kind)
+    (get-screen kind options)
+
+Get a screen object.
+
+`kind` is a [console constant](#consoles) describing the type of screen you
+want.  If unspecified it defaults to `:auto`.
+
+The `options` map can contain any of the following mappings:
+
+* `:cols` - Width of the desired screen in characters (default `80`).
+* `:rows` - Height of the desired screen in characters (default `24`).
+* `:charset` - Charset of the desired screen.  This should be a [charset
+  constant](#charsets) (default `:utf-8`).
+* `:resize-listener` - A function to call when the screen is resized.  This
+  function should take two parameters: the new number of columns, and the new
+  number of rows.
+
+The `:rows`, `:cols`, and `:charset` options are really just a suggestion!
+
+The text-based screens will ignore rows and columns and will be the size of
+the user's window.
+
+The Swing screen will start out at this size but can be resized later by the
+user, and will ignore the charset entirely.
+
+God only know what Cygwin will do.
+
+Your application needs to be flexible and handle sizes on the fly.
+
 ### lanterna.screen/start
+
+    :::clojure
+    (start screen)
+
+Start the given screen.  Screens must be started before they can be used.
+
+Consider using [`in-screen`](#lanternascreenin-screen) instead if you don't need
+detailed control of the starting and stopping.
+
 ### lanterna.screen/stop
+
+    :::clojure
+    (stop screen)
+
+Stop the given screen.  Screens must be stopped after you're done with them,
+otherwise you risk corrupting the user's console.
+
+Don't try to do anything to the screen after you stop it.
+
+I'm not sure if you can "restart" a screen once it's been stopped.  TODO: Find
+out.
+
+Consider using [`in-screen`](#lanternascreenin-screen) instead if you don't need
+detailed control of the starting and stopping.
+
 ### lanterna.screen/in-screen
+
+    :::clojure
+    (in-screen screen & body)
+
+Start the given screen, perform the body of expressions, and stop the screen
+afterward.
+
+This is a macro.
+
+The stopping will be done in a try/finally block, so you can be confident it
+will actually happen.
+
+Use this if you don't need detailed control of the screen starting and stopping
+process.
+
 ### lanterna.screen/redraw
+
+    :::clojure
+    (redraw screen)
+
+Redraw the given screen.
+
+This is how you actually flush any changes to the user's display.
+
 ### lanterna.screen/move-cursor
+
+    :::clojure
+    (move-cursor terminal x y)
+
+Move the cursor to a specific location on the screen.
+
+You'll need to [`redraw`](#lanternascreenredraw) the screen to actually see it
+happen.
+
+The cursor will stay where you move it, even if you later draw some text in
+a different place and redraw.  If you want it to move, you need to call this
+function again.
+
 ### lanterna.screen/put-string
+
+    :::clojure
+    (put-string screen x y s)
+    (put-string screen x y s options)
+
+Put a string on the screen buffer, ready to be drawn at the next
+[`redraw`](#lanternascreenredraw).
+
+`x` and `y` are the column and row to start the string.
+
+`s` is the actual string to draw.
+
+The `options` map can contain any of the following mappings:
+
+* `:fg` - Foreground color of the text.  Must be a [color constant](#colors)
+  (default `:default`).
+* `:bg` - Background color of the text.  Must be a [color constant](#colors)
+  (default `:default`).
+* `:styles` - Styles to apply to the text.  Must be a set containing zero or
+  more [style constants](#styles) (default `#{}`).  **CURRENTLY BROKEN, SORRY**
+
 ### lanterna.screen/get-key
+
+    :::clojure
+    (get-key screen)
+
+Get the next keypress from the user, or `nil` if none are buffered.
+
+If there is one or more keystroke buffered, that key will be returned (and
+popped off the buffer of input).  The returned key will be a [key code
+constant](#key-codes).
+
+If there are no keystrokes buffered, `nil` will be returned immediately.
+
+If you want to wait for user input, use
+[`get-key-blocking`](#lanternascreenget-key-blocking) instead.
+
 ### lanterna.screen/get-key-blocking
+
+    :::clojure
+    (get-key-blocking screen)
+
+Get the next keypress from the user.
+
+If there is one or more keystroke buffered, that key will be returned (and
+popped off the buffer of input).  The returned key will be a [key code
+constant](#key-codes).
+
+If there are no keystrokes buffered the function will sleep, checking every 50
+milliseconds for input.  Once there is a character buffered it will be popped
+off and returned as normal.
+
+If you want to return immediately instead of blocking when no input is buffered,
+use [`get-key`](#lanternascreenget-key) instead.
+
 ### lanterna.screen/add-resize-listener
+
+    :::clojure
+    (add-resize-listener screen listener-fn)
+
+Create a listener that will call the supplied function when the screen is
+resized.
+
+The function must take two arguments: the new number of columns and the new
+number of rows.
+
+You probably don't need this because you can specify a resize listener function
+when you call [`get-screen`](#lanternascreenget-screen).  It's here if you *do*
+need it though.
+

src/lanterna/screen.clj

@@ -20,11 +20,13 @@
 
   Options can contain one or more of the following keys:
 
-  :cols    - Width of the desired screen in characters. (default 80)
-  :rows    - Height of the desired screen in characters. (default 24)
-  :charset - Charset of the desired screen.
-             Can be any of (keys lanterna.constants/charsets).
-             (default :utf-8)
+  :cols    - Width of the desired screen in characters (default 80).
+  :rows    - Height of the desired screen in characters (default 24).
+  :charset - Charset of the desired screen.  Can be any of
+             (keys lanterna.constants/charsets) (default :utf-8).
+  :resize-listener - A function to call when the screen is resized.  This
+                     function should take two parameters: the new number of
+                     columns, and the new number of rows.
 
   NOTE: The options are really just a suggestion!