diff --git a/ldoc/prettify.lua b/ldoc/prettify.lua
index e4af2ac..9ba733e 100644
--- a/ldoc/prettify.lua
+++ b/ldoc/prettify.lua
@@ -1,51 +1,55 @@
-require 'pl'
-local lexer = require 'ldoc.lexer'
-local prettify = {}
-
-local escaped_chars = {
-    ['&'] = '&',
-    ['<'] = '&lt;',
-    ['>'] = '&gt;',
-}
-local escape_pat = '[&<>]'
-
-local function escape(str)
-    return (str:gsub(escape_pat,escaped_chars))
-end
-
-local function span(t,val)
-    return ('<span class="%s">%s</span>'):format(t,val)
-end
-
-local function link(file,ref,text)
-    text = text or ref
-    return ('<a class="L" href="%s.html#%s">%s</a>'):format(file,ref,text)
-end
-
-local spans = {keyword=true,number=true,string=true,comment=true}
-
-function prettify.lua (file)
-    local code,err = utils.readfile(file)
-    if not code then return nil,err end
-
-    local res = List()
-    res:append(header)
-    res:append '<pre>\n'
-
-    local tok = lexer.lua(code,{},{})
-    local t,val = tok()
-    while t do
-        val = escape(val)
-        if spans[t] then
-            res:append(span(t,val))
-        else
-            res:append(val)
-        end
-        --print(t,'|'..val..'|')
-        t,val = tok()
-    end
-    res:append(footer)
-    return res:join ()
-end
-
-return prettify
+-- Making Lua source code look pretty.
+-- A simple scanner based prettifier, which scans comments for @{ref} and code
+-- for known modules and functions.
+-- A module reference to an example `test-fun.lua` would look like
+-- `@{example:test-fun}`.
+require 'pl'
+local lexer = require 'ldoc.lexer'
+local prettify = {}
+
+local escaped_chars = {
+   ['&'] = '&amp;',
+   ['<'] = '&lt;',
+   ['>'] = '&gt;',
+}
+local escape_pat = '[&<>]'
+
+local function escape(str)
+   return (str:gsub(escape_pat,escaped_chars))
+end
+
+local function span(t,val)
+   return ('<span class="%s">%s</span>'):format(t,val)
+end
+
+local function link(file,ref,text)
+   text = text or ref
+   return ('<a class="L" href="%s.html#%s">%s</a>'):format(file,ref,text)
+end
+
+local spans = {keyword=true,number=true,string=true,comment=true}
+
+function prettify.lua (file)
+   local code,err = utils.readfile(file)
+   if not code then return nil,err end
+
+   local res = List()
+   res:append(header)
+   res:append '<pre>\n'
+
+   local tok = lexer.lua(code,{},{})
+   local t,val = tok()
+   while t do
+      val = escape(val)
+      if spans[t] then
+         res:append(span(t,val))
+      else
+         res:append(val)
+      end
+      t,val = tok()
+   end
+   res:append(footer)
+   return res:join ()
+end
+
+return prettify