From 02f2f80c8e7a1b5fc9999e390ff5f8bba8253784 Mon Sep 17 00:00:00 2001 From: "mrbkap%gmail.com" Date: Fri, 18 Feb 2005 18:30:48 +0000 Subject: [PATCH] bug 142260: Make doxygen comments in the htmlparser reflect reality. sr=bzbarsky git-svn-id: svn://10.0.0.236/trunk@169404 18797224-902f-48f8-a5cc-f745e15eee43 --- .../parser/htmlparser/src/nsHTMLTokenizer.cpp | 542 ++++++++++-------- 1 file changed, 304 insertions(+), 238 deletions(-) diff --git a/mozilla/parser/htmlparser/src/nsHTMLTokenizer.cpp b/mozilla/parser/htmlparser/src/nsHTMLTokenizer.cpp index 9711a8730b6..16eed2f04e7 100644 --- a/mozilla/parser/htmlparser/src/nsHTMLTokenizer.cpp +++ b/mozilla/parser/htmlparser/src/nsHTMLTokenizer.cpp @@ -38,9 +38,12 @@ /** - * MODULE NOTES: - * @update gess 4/1/98 - * + * @file nsHTMLTokenizer.cpp + * This is an implementation of the nsITokenizer interface. + * This file contains the implementation of a tokenizer to tokenize an HTML + * document. It attempts to do so, making tradeoffs between compatibility with + * older parsers and the SGML specification. Note that most of the real + * "tokenization" takes place in nsHTMLTokens.cpp. */ #include "nsIAtom.h" @@ -60,14 +63,13 @@ static NS_DEFINE_IID(kITokenizerIID, NS_ITOKENIZER_IID); static NS_DEFINE_IID(kClassIID, NS_HTMLTOKENIZER_IID); /** - * This method gets called as part of our COM-like interfaces. - * Its purpose is to create an interface to parser object - * of some type. + * This method gets called as part of our COM-like interfaces. + * Its purpose is to create an interface to parser object + * of some type. * - * @update gess 4/8/98 - * @param nsIID id of object to discover - * @param aInstancePtr ptr to newly discovered interface - * @return NS_xxx result code + * @param aIID id of object to discover + * @param aInstancePtr ptr to newly discovered interface + * @return NS_xxx result code */ nsresult nsHTMLTokenizer::QueryInterface(const nsIID& aIID, void** aInstancePtr) { @@ -75,13 +77,13 @@ nsresult nsHTMLTokenizer::QueryInterface(const nsIID& aIID, void** aInstancePtr) return NS_ERROR_NULL_POINTER; } - if(aIID.Equals(kISupportsIID)) { //do IUnknown... + if(aIID.Equals(kISupportsIID)) { // Do IUnknown... *aInstancePtr = (nsISupports*)(this); } - else if(aIID.Equals(kITokenizerIID)) { //do IParser base class... + else if(aIID.Equals(kITokenizerIID)) { // Do ITokenizer base class... *aInstancePtr = (nsITokenizer*)(this); } - else if(aIID.Equals(kClassIID)) { //do this class... + else if(aIID.Equals(kClassIID)) { // Do this class... *aInstancePtr = (nsHTMLTokenizer*)(this); } else { @@ -93,19 +95,21 @@ nsresult nsHTMLTokenizer::QueryInterface(const nsIID& aIID, void** aInstancePtr) } /** - * This method is defined in nsHTMLTokenizer.h. It is used to - * cause the COM-like construction of an HTMLTokenizer. + * This method is defined in nsHTMLTokenizer.h. It is used to + * cause the COM-like construction of an HTMLTokenizer. * - * @update gess 4/8/98 - * @param nsIParser** ptr to newly instantiated parser - * @return NS_xxx error result + * @param aInstancePtrResult** ptr to newly instantiated parser + * @param aFlag Parser flags the tokenizer should be aware of + * @param aDocType The doctype of the current document. + * @param aCommand The current command (view-source, fragment, etc). + * @return NS_xxx error result */ nsresult NS_NewHTMLTokenizer(nsITokenizer** aInstancePtrResult, - PRInt32 aFlag, - eParserDocType aDocType, - eParserCommands aCommand, - PRInt32 aFlags) + PRInt32 aFlag, + eParserDocType aDocType, + eParserCommands aCommand, + PRInt32 aFlags) { NS_PRECONDITION(nsnull != aInstancePtrResult, "null ptr"); if (nsnull == aInstancePtrResult) { @@ -124,11 +128,11 @@ NS_IMPL_RELEASE(nsHTMLTokenizer) /** - * Default constructor - * - * @update gess 4/9/98 - * @param - * @return + * Default constructor + * + * @param aParseMode The current mode the document is in (quirks, etc.) + * @param aDocType The document type of the current document + * @param aCommand What we are trying to do (view-source, parse a fragment, etc.) */ nsHTMLTokenizer::nsHTMLTokenizer(PRInt32 aParseMode, eParserDocType aDocType, @@ -174,13 +178,10 @@ nsHTMLTokenizer::nsHTMLTokenizer(PRInt32 aParseMode, /** - * Destructor - * - * @update gess 4/9/98 - * @param - * @return + * The destructor ensures that we don't leak any left over tokens. */ -nsHTMLTokenizer::~nsHTMLTokenizer(){ +nsHTMLTokenizer::~nsHTMLTokenizer() +{ if(mTokenDeque.GetSize()){ CTokenDeallocator theDeallocator(mTokenAllocator->GetArenaPool()); mTokenDeque.ForEach(theDeallocator); @@ -192,7 +193,23 @@ nsHTMLTokenizer::~nsHTMLTokenizer(){ Here begins the real working methods for the tokenizer. *******************************************************************/ -void nsHTMLTokenizer::AddToken(CToken*& aToken,nsresult aResult,nsDeque* aDeque,nsTokenAllocator* aTokenAllocator) { +/** + * Adds a token onto the end of the deque if aResult is a successful result. + * Otherwise, this function frees aToken and sets it to nsnull. + * + * @param aToken The token that wants to be added. + * @param aResult The error code that will be used to determine if we actually + * want to push this token. + * @param aDeque The deque we want to push aToken onto. + * @param aTokenAllocator The allocator we use to free aToken in case aResult + * is not a success code. + */ +/* static */ +void nsHTMLTokenizer::AddToken(CToken*& aToken, + nsresult aResult, + nsDeque* aDeque, + nsTokenAllocator* aTokenAllocator) +{ if(aToken && aDeque) { if(NS_SUCCEEDED(aResult)) { aDeque->Push(aToken); @@ -204,11 +221,12 @@ void nsHTMLTokenizer::AddToken(CToken*& aToken,nsresult aResult,nsDeque* aDeque, } /** - * Retrieve a ptr to the global token recycler... - * @update gess8/4/98 - * @return ptr to recycler (or null) + * Retrieve a pointer to the global token recycler... + * + * @return Pointer to recycler (or null) */ -nsTokenAllocator* nsHTMLTokenizer::GetTokenAllocator(void) { +nsTokenAllocator* nsHTMLTokenizer::GetTokenAllocator(void) +{ return mTokenAllocator; } @@ -216,10 +234,11 @@ nsTokenAllocator* nsHTMLTokenizer::GetTokenAllocator(void) { /** * This method provides access to the topmost token in the tokenDeque. * The token is not really removed from the list. - * @update gess8/2/98 - * @return ptr to token + * + * @return Pointer to token */ -CToken* nsHTMLTokenizer::PeekToken() { +CToken* nsHTMLTokenizer::PeekToken() +{ return (CToken*)mTokenDeque.PeekFront(); } @@ -227,10 +246,11 @@ CToken* nsHTMLTokenizer::PeekToken() { /** * This method provides access to the topmost token in the tokenDeque. * The token is really removed from the list; if the list is empty we return 0. - * @update gess8/2/98 - * @return ptr to token or NULL + * + * @return Pointer to token or NULL */ -CToken* nsHTMLTokenizer::PopToken() { +CToken* nsHTMLTokenizer::PopToken() +{ CToken* result=nsnull; result=(CToken*)mTokenDeque.PopFront(); return result; @@ -238,73 +258,82 @@ CToken* nsHTMLTokenizer::PopToken() { /** + * Pushes a token onto the front of our deque such that the next call to + * PopToken() or PeekToken() will return that token. * - * @update gess8/2/98 - * @param - * @return + * @param theToken The next token to be processed + * @return theToken */ -CToken* nsHTMLTokenizer::PushTokenFront(CToken* theToken) { +CToken* nsHTMLTokenizer::PushTokenFront(CToken* theToken) +{ mTokenDeque.PushFront(theToken); return theToken; } /** + * Pushes a token onto the deque. * - * @update gess8/2/98 - * @param - * @return + * @param theToken the new token. + * @return theToken */ -CToken* nsHTMLTokenizer::PushToken(CToken* theToken) { +CToken* nsHTMLTokenizer::PushToken(CToken* theToken) +{ mTokenDeque.Push(theToken); return theToken; } /** - * - * @update gess12/29/98 - * @param - * @return + * Returns the size of the deque. + * + * @return The number of remaining tokens. */ -PRInt32 nsHTMLTokenizer::GetCount(void) { +PRInt32 nsHTMLTokenizer::GetCount(void) +{ return mTokenDeque.GetSize(); } /** - * - * @update gess12/29/98 - * @param - * @return + * Allows access to an arbitrary token in the deque. The accessed token is left + * in the deque. + * + * @param anIndex The index of the target token. Token 0 would be the same as + * the result of a call to PeekToken() + * @return The requested token. */ -CToken* nsHTMLTokenizer::GetTokenAt(PRInt32 anIndex){ +CToken* nsHTMLTokenizer::GetTokenAt(PRInt32 anIndex) +{ return (CToken*)mTokenDeque.ObjectAt(anIndex); } /** - * @update gess 12/29/98 - * @update harishd 08/04/00 - * @param - * @return + * This method is part of the "sandwich" that occurs when we want to tokenize + * a document. This prepares us to be able to tokenize properly. + * + * @param aIsFinalChunk Whether this is the last chunk of data that we will + * get to see. + * @param aTokenAllocator The token allocator to use for this document. + * @return Our success in setting up. */ -nsresult nsHTMLTokenizer::WillTokenize(PRBool aIsFinalChunk,nsTokenAllocator* aTokenAllocator) +nsresult nsHTMLTokenizer::WillTokenize(PRBool aIsFinalChunk, + nsTokenAllocator* aTokenAllocator) { mTokenAllocator=aTokenAllocator; mIsFinalChunk=aIsFinalChunk; - mTokenScanPos=mTokenDeque.GetSize(); //cause scanDocStructure to search from here for new tokens... + // Cause ScanDocStructure to search from here for new tokens... + mTokenScanPos=mTokenDeque.GetSize(); return NS_OK; } /** - * - * @update gess12/29/98 - * @param - * @return + * Pushes all of the tokens in aDeque onto the front of our deque so they + * get processed before any other tokens. + * + * @param aDeque The deque with the tokens in it. */ -void nsHTMLTokenizer::PrependTokens(nsDeque& aDeque){ - +void nsHTMLTokenizer::PrependTokens(nsDeque& aDeque) +{ PRInt32 aCount=aDeque.GetSize(); - //last but not least, let's check the misplaced content list. - //if we find it, then we have to push it all into the body before continuing... PRInt32 anIndex=0; for(anIndex=0;anIndex 0) { if(theToken) { eHTMLTokenTypes theType = eHTMLTokenTypes(theToken->GetTokenType()); @@ -369,23 +398,21 @@ nsresult nsHTMLTokenizer::ScanDocStructure(PRBool aFinalChunk) { theToken = (CHTMLToken*)mTokenDeque.ObjectAt(--mTokenScanPos); } - /*---------------------------------------------------------------------- - * Now that we know where to start, let's walk through the - * tokens to see which are well-formed. Stop when you run out - * of fresh tokens. - *---------------------------------------------------------------------*/ + // Now that we know where to start, let's walk through the + // tokens to see which are well-formed. Stop when you run out + // of fresh tokens. nsDeque theStack(0); nsDeque tempStack(0); PRInt32 theStackDepth = 0; - //Don't bother if we get ridiculously deep. + // Don't bother if we get ridiculously deep. static const PRInt32 theMaxStackDepth = 200; while(theToken && theStackDepth < theMaxStackDepth) { eHTMLTokenTypes theType = eHTMLTokenTypes(theToken->GetTokenType()); eHTMLTags theTag = (eHTMLTags)theToken->GetTypeID(); - if(nsHTMLElement::IsContainer(theTag)) { //bug 54117 + if(nsHTMLElement::IsContainer(theTag)) { // Bug 54117 PRBool theTagIsBlock = gHTMLElements[theTag].IsMemberOf(kBlockEntity); PRBool theTagIsInline = (theTagIsBlock) ? PR_FALSE : @@ -460,7 +487,7 @@ nsresult nsHTMLTokenizer::ScanDocStructure(PRBool aFinalChunk) { break; default: break; - } //switch + } } } @@ -470,24 +497,31 @@ nsresult nsHTMLTokenizer::ScanDocStructure(PRBool aFinalChunk) { return result; } -nsresult nsHTMLTokenizer::DidTokenize(PRBool aFinalChunk) { +/** + * This method is called after we're done tokenizing a chunk of data. + * + * @param aFinalChunk Tells us if this was the last chunk of data. + * @return Error result. + */ +nsresult nsHTMLTokenizer::DidTokenize(PRBool aFinalChunk) +{ return ScanDocStructure(aFinalChunk); } /** - * This method repeatedly called by the tokenizer. - * Each time, we determine the kind of token were about to - * read, and then we call the appropriate method to handle - * that token type. + * This method is repeatedly called by the tokenizer. + * Each time, we determine the kind of token we're about to + * read, and then we call the appropriate method to handle + * that token type. * - * @update gess 3/25/98 - * @param aChar: last char read - * @param aScanner: see nsScanner.h - * @param anErrorCode: arg that will hold error condition - * @return new token or null + * @param aScanner The source of our input. + * @param aFlushTokens An OUT parameter to tell the caller whether it should + * process our queued tokens up to now (e.g., when we + * reach a