Updated readme, and a bit of commentary.

README.md

@@ -1,14 +1,13 @@
 
 # Pretty #
 
-`pretty` is an advanced pretty printer for [Lua](lua.org) aiming primarily for
+`pretty` is an advanced pretty printer for [Lua](lua.org). It's primarily a
-human readability. It does this by looking for patterns in the input data, and
+debugging tool, aiming for human readability, by detecting pattern in the input
-creating an output string utilizing and highlighting those patterns. Thus it's
+data, and creating an output string utilizing and highlighting those patterns.
-a primarily a debugging tool, not a speedy serialization tool.
 
 ## Code Example
 
-Setup is simple, just `pretty = require 'pretty'`, and you're good to go.
+Setup is simple, use `pretty = require 'pretty'`, and you're good to go.
 
 ```lua
 > print(pretty( { 1, 2, 3 } ))
@@ -79,24 +78,27 @@ available.
 
 ## Installation
 
-TODO
+`pretty` is loadable directly with `require`. Either clone or download this
+repository. Where you place it, depends upon what you want to do:
+
+1.	**You want `pretty` in a specific project**: Place the `pretty` folder
+	somewhere in your project, and `require` it from one of your project files.
+2.	**You want `pretty` on your system**: Place the `pretty` folder such that
+	it's visible from your Lua-path. On my system this might be
+	`/usr/local/share/lua/5.1/`. Now you can `require` it from anywhere.
 
 ## API Documentation
 
-TODO
+`pretty` exposes a single function, the `pretty` function itself. It's function
+signature is `pretty(value, options)`. `value` can be any Lua value. `options`
+must be a table.
 
-## Tests
+### List of options
 
-TODO
+`pretty` is sure to complain if you give it an unknown option, or if you give an
+option a bad value.
 
-## Performance
+-	`indent: string`: The string to indent with. Four spaces (`    `) by default.
-
-As specified in the introduction, `pretty` is not a performance oriented
-library. Expected usage is in error conditions and debugging, not in tight
-inner loops.
-
-Don't use `pretty.lua` if you want fast serialization. Use one of the pretty
-printers specified below.
 
 ## TODO
 
@@ -108,23 +110,20 @@ I'm looking into implementing following features:
 -	Provide nice formatting for `cdata` datatype in LuaJIT.
 -	Expand on the comment output in output, for `__tostring` methods, and global
 	namespaces like `io` or `math`.
--	Look into using concat operation to improve appearance of overly long
-	non-breaking strings. Attempt to break near whitespace.
 -	Attempt to fit output within a predefined width limit. Default to 80.
 -	Add option for colored output. Primarily syntax highlighting, but also
 	[BlueJ-style](www.bluej.org/about.html) scope highlighting, with some faint
 	background colors.
--	Look more into `string.dump` in the core library.
 -	Find a better name than `pretty`.
 
-## Other pretty printers
+## Alternative pretty printers
 
 `pretty` is large, slow, and requires the debug library to work. It's not
 designed for serialization purposes, nor is it concerned with offering the same
 level of customization as other libraries do.
 
-If you want a sleek, fast, customizable or embeddable library, there are other
+If you want a sleek, fast, customizable or embeddable library, there are
-options. Lua has a large library of pretty printers and serialization libraries:
+thankfully other options.
 
 -	[inspect.lua](github.com/kikito/inspect.lua): One of the classic debugging
 	pretty printers.
@@ -136,12 +135,12 @@ options. Lua has a large library of pretty printers and serialization libraries:
 -	[binser](github.com/bakpakin/binser): Library for special purpose
 	serialization.
 
-Find others at [the lua-users wiki](lua-users.org/wiki/TableSerialization).
+Even more are available at [the lua-users wiki](lua-users.org/wiki/TableSerialization).
 
 ## Contact
 
 The author is available at `jonjmaa (at) gmail.com`. Be sure to send an email if
-you have ideas for improvements, find an issue, or even an unintuitive result.
+you have ideas for improvements, or find an issue.
 
 ## License
 

function.lua

@@ -111,7 +111,7 @@ local function get_function_info (f)
 
     if     info.source:sub(1,1) == '=' then  info.defined_how = 'C'
 	elseif info.source:sub(1,1) == '@' then  info.defined_how = 'file'
-    elseif info.source:find'^%w+.lua$' then  info.defined_how = 'file'    -- XXX: Hotfix for Love2d boot.lua issue.
+    elseif info.source:find'^%w+.lua$' then  info.defined_how = 'file'    -- Hotfix for Love2d boot.lua issue.
     else                                     info.defined_how = 'string'
     end
 
@@ -233,6 +233,8 @@ local function width_of_strings_in_l (l, start_i, end_i)
 end
 
 local function add_indent_to_string (str, indent)
+	-- Indents `str` by `indent`.
+
 	assert(type(str)    == 'string')
 	assert(type(indent) == 'string')
 
@@ -240,12 +242,16 @@ local function add_indent_to_string (str, indent)
 end
 
 local function wrap_text (text, max_width)
+	-- Creates a wrapped version of given `text`, with no lines longer than
+	-- `max_width`. Splits only at whitespace.
+
+	-- TODO: Fix this.
+
 	local l, i, last_i  =  {}, max_width, 1
 	repeat
 		if text:sub(i, i) == ' ' then
 			l[#l+1], last_i, i  =  text:sub(last_i, i - 1), i + 1, i + max_width
 		elseif i <= last_i then
-			-- TODO: Make sure this part works.
 			i = text:find(' ', last_i) or #text
 		else
 			i = i - 1

pretty.lua

@@ -393,8 +393,6 @@ local TABLE_TYPE_TO_PAIR_FORMAT = {
 -- Formatting tables
 
 local function format_table (t, depth, l)
-    -- TODO: Add more nuanced formatting.
-
     -- Error Checking
     assert(type(t) == 'table')
     assert(type(depth) == 'number' and type(l) == 'table')
@@ -518,12 +516,12 @@ setmetatable(StringBuilder, {
 local DEBUG_OPTION_USED = {  }
 
 local KNOWN_OPTIONS = {
-    _table_addr_comment = { type = 'boolean', default = false, debug = 'debug' },
+    _table_addr_comment = { type = 'boolean', default = false, debug = 'debug' }, -- TODO: Maybe automatically display table address when depth = 0?
 
     indent              = { type = 'string',  default = '    ' },
     max_depth           = { type = 'number',  default = math.huge },
     short_builtins      = { type = 'boolean', default = false }, -- TODO: Outphase this. Rather automatically use the short versions in places where it would be strange to find the function, like keys, etc.
-    recursion           = { type = 'string',  default = 'ignore', accepted = {['ignore'] = true, ['marked'] = true, ['revisit'] = true} },
+    recursion           = { type = 'string',  default = 'ignore', accepted = {['ignore'] = true, ['marked'] = true, ['revisit'] = true} }, -- TODO: Completely depricate this option. I do not like it.
 }
 
 local function ensure_that_all_options_are_known (input_options)

pstring.lua

@@ -4,7 +4,7 @@
 
 --[=[ Thoughts on displaying strings in the useful ways.
 
-TODO
+Thoughts are TODO
 
 --]=]
 
@@ -135,6 +135,8 @@ local function format_concatted_string (str, depth, l)
 	-- Cuts the string up into smaller individual substrings, each Concatted
 	-- together. Is uglier compared to longform, but is at least idempotent.
 
+	-- TODO: Attempt to cut near whitespace?
+
 	-- Error checking
 	assert( type(str) == 'string' )
 	assert(type(depth) == 'number' and type(l) == 'table')