Describe the HeaderParser class.

Doc/lib/emailparser.tex

@@ -24,6 +24,17 @@ no magical connection between the \module{email} package's bundled
 parser and the \class{Message} class, so your custom parser can create
 message object trees in any way it find necessary.
 
+The primary parser class is \class{Parser} which parses both the
+headers and the payload of the message.  In the case of
+\mimetype{multipart} messages, it will recursively parse the body of
+the container message.  The \module{email.Parser} module also provides
+a second class, called \class{HeaderParser} which can be used if
+you're only interested in the headers of the message.
+\class{HeaderParser} can be much faster in this situations, since it
+does not attempt to parse the message body, instead setting the
+payload to the raw body as a string.  \class{HeaderParser} has the
+same API as the \class{Parser} class.
+
 \subsubsection{Parser class API}
 
 \begin{classdesc}{Parser}{\optional{_class}}