Index: code-docs/crystalize.scrbl
==================================================================
--- code-docs/crystalize.scrbl
+++ code-docs/crystalize.scrbl
@@ -10,10 +10,11 @@
                      "../cache.rkt"
                      racket/base
                      racket/contract
                      racket/string
                      txexpr
+                     pollen/core
                      pollen/pagetree))
 
 @title[#:tag "crystalize-rkt"]{Crystalize}
 
 @defmodule["crystalize.rkt" #:packages ()]
@@ -25,25 +26,32 @@
 through the Pollen cache for matching docs and regenerating the HTML.
 
 @margin-note{These functions are designed to be used within the template for articles and series,
 respectively, so that the cache is updated precisely when the web page is rendered.}
 
-@defproc[(parse-and-cache-article! [pagenode pagenode?] [doc txexpr?]) non-empty-string?]{
+@defproc[(parse-and-cache-article! [pagenode pagenode?] [doc txexpr?]) 
+         (values non-empty-string? non-empty-string?)]{
+
+Returns two values: the “plain” title of the article, and a string containing the full HTML of
+@racket[_doc], in that order.
 
-Returns a string containing the HTML of @racket[_doc]. 
+The title is returned separately for use in the HTML @tt{<title>} tag. If the @racket[_doc] doesn’t
+specify a title, a provisional title is constructed using @racket[default-title].
 
 Privately, it does a lot of other work. The article is analyzed, additional metadata is constructed
 and saved to the SQLite cache and saved using @racket[make-cache:article]. If the article specifies
 a @racket['series] meta, information about that series is fetched and used in the rendering of the
 article. If there are @racket[note]s or @racket[index] tags in the doc, they are parsed and saved
-individually to the SQLite cache (using @racket[make-cache:note] and @racket[make-cache:index-entry]
-respectively). If any of the notes use the @code{#:disposition} attribute, information about the
-disposition is parsed out and used in the rendering of the article.
+individually to the SQLite cache (using @racket[make-cache:note] and
+@racket[make-cache:index-entry]). If any of the notes use the @code{#:disposition} attribute,
+information about the disposition is parsed out and used in the rendering of the article. 
+
 }
 
 @defproc[(cache-series!) void?]{
 
 Attempts to look up certain values in @racket[current-metas] which we expect to be defined on
 a typical series page, and saves them to the cache using @racket[make-cache:series]. If @tt{title}
 is not defined in the current metas, you’ll get an error. If any of the others are missing, an empty
 string is used.
+
 }