From e7204f5a100642c783278e74e70c996d37815d7e Mon Sep 17 00:00:00 2001
From: "cbiesinger%web.de" <cbiesinger%web.de>
Date: Tue, 11 May 2004 14:27:59 +0000
Subject: [PATCH] nsTXTToHTMLConv could use some documentation r+sr=darin bug
 243243

---
 .../streamconv/converters/nsTXTToHTMLConv.cpp |  2 ++
 .../streamconv/converters/nsTXTToHTMLConv.h   | 30 ++++++++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/netwerk/streamconv/converters/nsTXTToHTMLConv.cpp b/netwerk/streamconv/converters/nsTXTToHTMLConv.cpp
index 8c728945735e..fb8a7f52fcd0 100644
--- a/netwerk/streamconv/converters/nsTXTToHTMLConv.cpp
+++ b/netwerk/streamconv/converters/nsTXTToHTMLConv.cpp
@@ -153,10 +153,12 @@ nsTXTToHTMLConv::OnDataAvailable(nsIRequest* request, nsISupports *aContext,
     
     do {
         PRUint32 read = 0;
+        // XXX readSegments, to avoid the first copy?
         rv = aInStream->Read(buffer, aCount-amtRead, &read);
         if (NS_FAILED(rv)) return rv;
 
         buffer[read] = '\0';
+        // XXX charsets?? non-latin1 characters?? utf-16??
         mBuffer.AppendWithConversion(buffer);
         amtRead += read;
 
diff --git a/netwerk/streamconv/converters/nsTXTToHTMLConv.h b/netwerk/streamconv/converters/nsTXTToHTMLConv.h
index 4607477c8e28..fce4003f329d 100644
--- a/netwerk/streamconv/converters/nsTXTToHTMLConv.h
+++ b/netwerk/streamconv/converters/nsTXTToHTMLConv.h
@@ -59,6 +59,34 @@ typedef struct convToken {
     PRBool   prepend;   // flag indicating how the modText should be used.
 } convToken;
     
+/**
+ * Convert plain text to HTML.
+ *
+ * OVERVIEW OF HOW THIS CLASS WORKS:
+ *
+ * This class stores an array of tokens that should be replaced by something,
+ * or something that should be prepended.
+ * The "token" member of convToken is the text to search for. This is a
+ * substring of the desired token. Tokens are delimited by TOKEN_DELIMITERS.
+ * That entire token will be replaced by modText (if prepend is false); or it
+ * will be linkified and modText will be prepended to the token if prepend is
+ * true.
+ *
+ * Note that all of the text will be in a preformatted block, so there is no
+ * need to emit line-end tags, or set the font face to monospace.
+ *
+ * This works as a stream converter, so data will arrive by
+ * OnStartRequest/OnDataAvailable/OnStopRequest calls.
+ *
+ * OStopR will possibly process a remaining token.
+ *
+ * If the data of one pass contains a part of a token, that part will be stored
+ * in mBuffer. The rest of the data will be sent to the next listener.
+ * 
+ * XXX this seems suboptimal. this means that this design will only work for
+ * links. and it is impossible to append anything to the token. this means that,
+ * for example, making *foo* bold is not possible.
+ */
 class nsTXTToHTMLConv : public nsITXTToHTMLConv {
 public:
     NS_DECL_ISUPPORTS
@@ -98,7 +126,7 @@ protected:
     PRInt32 FindToken(PRInt32 cursor, convToken* *_retval);
 
     // return the cursor location after munging HTML into the 
-    // underlying buffer.
+    // underlying buffer, according to mToken
     PRInt32 CatHTML(PRInt32 front, PRInt32 back);
 
     nsCOMPtr<nsIStreamListener>     mListener; // final listener (consumer)