added doc tool

1 files changed, 1331 insertions, 0 deletions

diff --git a/docs/tool/Modules/NaturalDocs/Parser.pm b/docs/tool/Modules/NaturalDocs/Parser.pm
new file mode 100644
index 00000000..e88cd289
--- /dev/null
+++ b/docs/tool/Modules/NaturalDocs/Parser.pm
@@ -0,0 +1,1331 @@
+###############################################################################
+#
+#   Package: NaturalDocs::Parser
+#
+###############################################################################
+#
+#   A package that coordinates source file parsing between the <NaturalDocs::Languages::Base>-derived objects and its own
+#   sub-packages such as <NaturalDocs::Parser::Native>.  Also handles sending symbols to <NaturalDocs::SymbolTable> and
+#   other generic topic processing.
+#
+#   Usage and Dependencies:
+#
+#       - Prior to use, <NaturalDocs::Settings>, <NaturalDocs::Languages>, <NaturalDocs::Project>, <NaturalDocs::SymbolTable>,
+#         and <NaturalDocs::ClassHierarchy> must be initialized.  <NaturalDocs::SymbolTable> and <NaturalDocs::ClassHierarchy>
+#         do not have to be fully resolved.
+#
+#       - Aside from that, the package is ready to use right away.  It does not have its own initialization function.
+#
+###############################################################################
+
+# This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg Valure
+# Natural Docs is licensed under the GPL
+
+use NaturalDocs::Parser::ParsedTopic;
+use NaturalDocs::Parser::Native;
+use NaturalDocs::Parser::JavaDoc;
+
+use strict;
+use integer;
+
+package NaturalDocs::Parser;
+
+
+
+###############################################################################
+# Group: Variables
+
+
+#
+#   var: sourceFile
+#
+#   The source <FileName> currently being parsed.
+#
+my $sourceFile;
+
+#
+#   var: language
+#
+#   The language object for the file, derived from <NaturalDocs::Languages::Base>.
+#
+my $language;
+
+#
+#   Array: parsedFile
+#
+#   An array of <NaturalDocs::Parser::ParsedTopic> objects.
+#
+my @parsedFile;
+
+
+#
+#   bool: parsingForInformation
+#   Whether <ParseForInformation()> was called.  If false, then <ParseForBuild()> was called.
+#
+my $parsingForInformation;
+
+
+
+###############################################################################
+# Group: Functions
+
+#
+#   Function: ParseForInformation
+#
+#   Parses the input file for information.  Will update the information about the file in <NaturalDocs::SymbolTable> and
+#   <NaturalDocs::Project>.
+#
+#   Parameters:
+#
+#       file - The <FileName> to parse.
+#
+sub ParseForInformation #(file)
+    {
+    my ($self, $file) = @_;
+    $sourceFile = $file;
+
+    $parsingForInformation = 1;
+
+    # Watch this parse so we detect any changes.
+    NaturalDocs::SymbolTable->WatchFileForChanges($sourceFile);
+    NaturalDocs::ClassHierarchy->WatchFileForChanges($sourceFile);
+    NaturalDocs::SourceDB->WatchFileForChanges($sourceFile);
+
+    my $defaultMenuTitle = $self->Parse();
+
+    foreach my $topic (@parsedFile)
+        {
+        # Add a symbol for the topic.
+
+        my $type = $topic->Type();
+        if ($type eq ::TOPIC_ENUMERATION())
+            {  $type = ::TOPIC_TYPE();  };
+
+        NaturalDocs::SymbolTable->AddSymbol($topic->Symbol(), $sourceFile, $type,
+                                                                   $topic->Prototype(), $topic->Summary());
+
+
+        # You can't put the function call directly in a while with a regex.  It has to sit in a variable to work.
+        my $body = $topic->Body();
+
+
+        # If it's a list or enum topic, add a symbol for each description list entry.
+
+        if ($topic->IsList() || $topic->Type() eq ::TOPIC_ENUMERATION())
+            {
+            # We'll hijack the enum constants to apply to non-enum behavior too.
+            my $behavior;
+
+            if ($topic->Type() eq ::TOPIC_ENUMERATION())
+                {
+                $type = ::TOPIC_CONSTANT();
+                $behavior = $language->EnumValues();
+                }
+            elsif (NaturalDocs::Topics->TypeInfo($topic->Type())->Scope() == ::SCOPE_ALWAYS_GLOBAL())
+                {
+                $behavior = ::ENUM_GLOBAL();
+                }
+            else
+                {
+                $behavior = ::ENUM_UNDER_PARENT();
+                };
+
+            while ($body =~ /<ds>([^<]+)<\/ds><dd>(.*?)<\/dd>/g)
+                {
+                my ($listTextSymbol, $listSummary) = ($1, $2);
+
+                $listTextSymbol = NaturalDocs::NDMarkup->RestoreAmpChars($listTextSymbol);
+                my $listSymbol = NaturalDocs::SymbolString->FromText($listTextSymbol);
+
+                if ($behavior == ::ENUM_UNDER_PARENT())
+                    {  $listSymbol = NaturalDocs::SymbolString->Join($topic->Package(), $listSymbol);  }
+                elsif ($behavior == ::ENUM_UNDER_TYPE())
+                    {  $listSymbol = NaturalDocs::SymbolString->Join($topic->Symbol(), $listSymbol);  };
+
+                NaturalDocs::SymbolTable->AddSymbol($listSymbol, $sourceFile, $type, undef,
+                                                                           $self->GetSummaryFromDescriptionList($listSummary));
+                };
+            };
+
+
+        # Add references in the topic.
+
+        while ($body =~ /<link target=\"([^\"]*)\" name=\"[^\"]*\" original=\"[^\"]*\">/g)
+            {
+            my $linkText = NaturalDocs::NDMarkup->RestoreAmpChars($1);
+            my $linkSymbol = NaturalDocs::SymbolString->FromText($linkText);
+
+            NaturalDocs::SymbolTable->AddReference(::REFERENCE_TEXT(), $linkSymbol,
+                                                                           $topic->Package(), $topic->Using(), $sourceFile);
+            };
+
+
+        # Add images in the topic.
+
+        while ($body =~ /<img mode=\"[^\"]*\" target=\"([^\"]+)\" original=\"[^\"]*\">/g)
+            {
+            my $target = NaturalDocs::NDMarkup->RestoreAmpChars($1);
+            NaturalDocs::ImageReferenceTable->AddReference($sourceFile, $target);
+            };
+        };
+
+    # Handle any changes to the file.
+    NaturalDocs::ClassHierarchy->AnalyzeChanges();
+    NaturalDocs::SymbolTable->AnalyzeChanges();
+    NaturalDocs::SourceDB->AnalyzeWatchedFileChanges();
+
+    # Update project on the file's characteristics.
+    my $hasContent = (scalar @parsedFile > 0);
+
+    NaturalDocs::Project->SetHasContent($sourceFile, $hasContent);
+    if ($hasContent)
+        {  NaturalDocs::Project->SetDefaultMenuTitle($sourceFile, $defaultMenuTitle);  };
+
+    # We don't need to keep this around.
+    @parsedFile = ( );
+    };
+
+
+#
+#   Function: ParseForBuild
+#
+#   Parses the input file for building, returning it as a <NaturalDocs::Parser::ParsedTopic> arrayref.
+#
+#   Note that all new and changed files should be parsed for symbols via <ParseForInformation()> before calling this function on
+#   *any* file.  The reason is that <NaturalDocs::SymbolTable> needs to know about all the symbol definitions and references to
+#   resolve them properly.
+#
+#   Parameters:
+#
+#       file - The <FileName> to parse for building.
+#
+#   Returns:
+#
+#       An arrayref of the source file as <NaturalDocs::Parser::ParsedTopic> objects.
+#
+sub ParseForBuild #(file)
+    {
+    my ($self, $file) = @_;
+    $sourceFile = $file;
+
+    $parsingForInformation = undef;
+
+    $self->Parse();
+
+    return \@parsedFile;
+    };
+
+
+
+
+###############################################################################
+# Group: Interface Functions
+
+
+#
+#   Function: OnComment
+#
+#   The function called by <NaturalDocs::Languages::Base>-derived objects when their parsers encounter a comment
+#   suitable for documentation.
+#
+#   Parameters:
+#
+#       commentLines - An arrayref of the comment's lines.  The language's comment symbols should be converted to spaces,
+#                               and there should be no line break characters at the end of each line.  *The original memory will be
+#                               changed.*
+#       lineNumber - The line number of the first of the comment lines.
+#       isJavaDoc - Whether the comment is in JavaDoc format.
+#
+#   Returns:
+#
+#       The number of topics created by this comment, or zero if none.
+#
+sub OnComment #(string[] commentLines, int lineNumber, bool isJavaDoc)
+    {
+    my ($self, $commentLines, $lineNumber, $isJavaDoc) = @_;
+
+    $self->CleanComment($commentLines);
+
+    # We check if it's definitely Natural Docs content first.  This overrides all else, since it's possible that a comment could start
+    # with a topic line yet have something that looks like a JavaDoc tag.  Natural Docs wins in this case.
+    if (NaturalDocs::Parser::Native->IsMine($commentLines, $isJavaDoc))
+        {  return NaturalDocs::Parser::Native->ParseComment($commentLines, $isJavaDoc, $lineNumber, \@parsedFile);  }
+
+    elsif (NaturalDocs::Parser::JavaDoc->IsMine($commentLines, $isJavaDoc))
+        {  return NaturalDocs::Parser::JavaDoc->ParseComment($commentLines, $isJavaDoc, $lineNumber, \@parsedFile);  }
+
+    # If the content is ambiguous and it's a JavaDoc-styled comment, treat it as Natural Docs content.
+    elsif ($isJavaDoc)
+        {  return NaturalDocs::Parser::Native->ParseComment($commentLines, $isJavaDoc, $lineNumber, \@parsedFile);  }
+    };
+
+
+#
+#   Function: OnClass
+#
+#   A function called by <NaturalDocs::Languages::Base>-derived objects when their parsers encounter a class declaration.
+#
+#   Parameters:
+#
+#       class - The <SymbolString> of the class encountered.
+#
+sub OnClass #(class)
+    {
+    my ($self, $class) = @_;
+
+    if ($parsingForInformation)
+        {  NaturalDocs::ClassHierarchy->AddClass($sourceFile, $class);  };
+    };
+
+
+#
+#   Function: OnClassParent
+#
+#   A function called by <NaturalDocs::Languages::Base>-derived objects when their parsers encounter a declaration of
+#   inheritance.
+#
+#   Parameters:
+#
+#       class - The <SymbolString> of the class we're in.
+#       parent - The <SymbolString> of the class it inherits.
+#       scope - The package <SymbolString> that the reference appeared in.
+#       using - An arrayref of package <SymbolStrings> that the reference has access to via "using" statements.
+#       resolvingFlags - Any <Resolving Flags> to be used when resolving the reference.  <RESOLVE_NOPLURAL> is added
+#                              automatically since that would never apply to source code.
+#
+sub OnClassParent #(class, parent, scope, using, resolvingFlags)
+    {
+    my ($self, $class, $parent, $scope, $using, $resolvingFlags) = @_;
+
+    if ($parsingForInformation)
+        {
+        NaturalDocs::ClassHierarchy->AddParentReference($sourceFile, $class, $parent, $scope, $using,
+                                                                                   $resolvingFlags | ::RESOLVE_NOPLURAL());
+        };
+    };
+
+
+
+###############################################################################
+# Group: Support Functions
+
+
+#   Function: Parse
+#
+#   Opens the source file and parses process.  Most of the actual parsing is done in <NaturalDocs::Languages::Base->ParseFile()>
+#   and <OnComment()>, though.
+#
+#   *Do not call externally.*  Rather, call <ParseForInformation()> or <ParseForBuild()>.
+#
+#   Returns:
+#
+#       The default menu title of the file.  Will be the <FileName> if nothing better is found.
+#
+sub Parse
+    {
+    my ($self) = @_;
+
+    NaturalDocs::Error->OnStartParsing($sourceFile);
+
+    $language = NaturalDocs::Languages->LanguageOf($sourceFile);
+    NaturalDocs::Parser::Native->Start();
+    @parsedFile = ( );
+
+    my ($autoTopics, $scopeRecord) = $language->ParseFile($sourceFile, \@parsedFile);
+
+
+    $self->AddToClassHierarchy();
+
+    $self->BreakLists();
+
+    if (defined $autoTopics)
+        {
+        if (defined $scopeRecord)
+            {  $self->RepairPackages($autoTopics, $scopeRecord);  };
+
+        $self->MergeAutoTopics($language, $autoTopics);
+        };
+
+    $self->RemoveRemainingHeaderlessTopics();
+
+
+    # We don't need to do this if there aren't any auto-topics because the only package changes would be implied by the comments.
+    if (defined $autoTopics)
+        {  $self->AddPackageDelineators();  };
+
+    if (!NaturalDocs::Settings->NoAutoGroup())
+        {  $self->MakeAutoGroups($autoTopics);  };
+
+
+    # Set the menu title.
+
+    my $defaultMenuTitle = $sourceFile;
+
+    if (scalar @parsedFile)
+        {
+        my $addFileTitle;
+
+        if (NaturalDocs::Settings->OnlyFileTitles())
+            {
+            # We still want to use the title from the topics if the first one is a file.
+            if ($parsedFile[0]->Type() eq ::TOPIC_FILE())
+                {  $addFileTitle = 0;  }
+            else
+                {  $addFileTitle = 1;  };
+            }
+        elsif (scalar @parsedFile == 1 || NaturalDocs::Topics->TypeInfo( $parsedFile[0]->Type() )->PageTitleIfFirst())
+            {  $addFileTitle = 0;  }
+        else
+            {  $addFileTitle = 1;  };
+
+        if (!$addFileTitle)
+            {
+            $defaultMenuTitle = $parsedFile[0]->Title();
+            }
+        else
+            {
+            # If the title ended up being the file name, add a leading section for it.
+
+            unshift @parsedFile,
+                       NaturalDocs::Parser::ParsedTopic->New(::TOPIC_FILE(), (NaturalDocs::File->SplitPath($sourceFile))[2],
+                                                                                  undef, undef, undef, undef, undef, 1, undef);
+            };
+        };
+
+    NaturalDocs::Error->OnEndParsing($sourceFile);
+
+    return $defaultMenuTitle;
+    };
+
+
+#
+#   Function: CleanComment
+#
+#   Removes any extraneous formatting and whitespace from the comment.  Eliminates comment boxes, horizontal lines, trailing
+#   whitespace from lines, and expands all tab characters.  It keeps leading whitespace, though, since it may be needed for
+#   example code, and blank lines, since the original line numbers are needed.
+#
+#   Parameters:
+#
+#       commentLines  - An arrayref of the comment lines to clean.  *The original memory will be changed.*  Lines should have the
+#                                language's comment symbols replaced by spaces and not have a trailing line break.
+#
+sub CleanComment #(commentLines)
+    {
+    my ($self, $commentLines) = @_;
+
+    use constant DONT_KNOW => 0;
+    use constant IS_UNIFORM => 1;
+    use constant IS_UNIFORM_IF_AT_END => 2;
+    use constant IS_NOT_UNIFORM => 3;
+
+    my $leftSide = DONT_KNOW;
+    my $rightSide = DONT_KNOW;
+    my $leftSideChar;
+    my $rightSideChar;
+
+    my $index = 0;
+    my $tabLength = NaturalDocs::Settings->TabLength();
+
+    while ($index < scalar @$commentLines)
+        {
+        # Strip trailing whitespace from the original.
+
+        $commentLines->[$index] =~ s/[ \t]+$//;
+
+
+        # Expand tabs in the original.  This method is almost six times faster than Text::Tabs' method.
+
+        my $tabIndex = index($commentLines->[$index], "\t");
+
+        while ($tabIndex != -1)
+            {
+            substr( $commentLines->[$index], $tabIndex, 1, ' ' x ($tabLength - ($tabIndex % $tabLength)) );
+            $tabIndex = index($commentLines->[$index], "\t", $tabIndex);
+            };
+
+
+        # Make a working copy and strip leading whitespace as well.  This has to be done after tabs are expanded because
+        # stripping indentation could change how far tabs are expanded.
+
+        my $line = $commentLines->[$index];
+        $line =~ s/^ +//;
+
+        # If the line is blank...
+        if (!length $line)
+            {
+            # If we have a potential vertical line, this only acceptable if it's at the end of the comment.
+            if ($leftSide == IS_UNIFORM)
+                {  $leftSide = IS_UNIFORM_IF_AT_END;  };
+            if ($rightSide == IS_UNIFORM)
+                {  $rightSide = IS_UNIFORM_IF_AT_END;  };
+            }
+
+        # If there's at least four symbols in a row, it's a horizontal line.  The second regex supports differing edge characters.  It
+        # doesn't matter if any of this matches the left and right side symbols.  The length < 256 is a sanity check, because that
+        # regexp has caused the perl regexp engine to choke on an insane line someone sent me from an automatically generated
+        # file.  It had over 10k characters on the first line, and most of them were 0x00.
+        elsif ($line =~ /^([^a-zA-Z0-9 ])\1{3,}$/ ||
+                (length $line < 256 && $line =~ /^([^a-zA-Z0-9 ])\1*([^a-zA-Z0-9 ])\2{3,}([^a-zA-Z0-9 ])\3*$/) )
+            {
+            # Ignore it.  This has no effect on the vertical line detection.  We want to keep it in the output though in case it was
+            # in a code section.
+            }
+
+        # If the line is not blank or a horizontal line...
+        else
+            {
+            # More content means any previous blank lines are no longer tolerated in vertical line detection.  They are only
+            # acceptable at the end of the comment.
+
+            if ($leftSide == IS_UNIFORM_IF_AT_END)
+                {  $leftSide = IS_NOT_UNIFORM;  };
+            if ($rightSide == IS_UNIFORM_IF_AT_END)
+                {  $rightSide = IS_NOT_UNIFORM;  };
+
+
+            # Detect vertical lines.  Lines are only lines if they are followed by whitespace or a connected horizontal line.
+            # Otherwise we may accidentally detect lines from short comments that just happen to have every first or last
+            # character the same.
+
+            if ($leftSide != IS_NOT_UNIFORM)
+                {
+                if ($line =~ /^([^a-zA-Z0-9])\1*(?: |$)/)
+                    {
+                    if ($leftSide == DONT_KNOW)
+                        {
+                        $leftSide = IS_UNIFORM;
+                        $leftSideChar = $1;
+                        }
+                    else # ($leftSide == IS_UNIFORM)  Other choices already ruled out.
+                        {
+                        if ($leftSideChar ne $1)
+                            {  $leftSide = IS_NOT_UNIFORM;  };
+                        };
+                    }
+                # We'll tolerate the lack of symbols on the left on the first line, because it may be a
+                # /* Function: Whatever
+                #  * Description.
+                #  */
+                # comment which would have the leading /* blanked out.
+                elsif ($index != 0)
+                    {
+                    $leftSide = IS_NOT_UNIFORM;
+                    };
+                };
+
+            if ($rightSide != IS_NOT_UNIFORM)
+                {
+                if ($line =~ / ([^a-zA-Z0-9])\1*$/)
+                    {
+                    if ($rightSide == DONT_KNOW)
+                        {
+                        $rightSide = IS_UNIFORM;
+                        $rightSideChar = $1;
+                        }
+                    else # ($rightSide == IS_UNIFORM)  Other choices already ruled out.
+                        {
+                        if ($rightSideChar ne $1)
+                            {  $rightSide = IS_NOT_UNIFORM;  };
+                        };
+                    }
+                else
+                    {
+                    $rightSide = IS_NOT_UNIFORM;
+                    };
+                };
+
+            # We'll remove vertical lines later if they're uniform throughout the entire comment.
+            };
+
+        $index++;
+        };
+
+
+    if ($leftSide == IS_UNIFORM_IF_AT_END)
+        {  $leftSide = IS_UNIFORM;  };
+    if ($rightSide == IS_UNIFORM_IF_AT_END)
+        {  $rightSide = IS_UNIFORM;  };
+
+
+    $index = 0;
+    my $inCodeSection = 0;
+
+    while ($index < scalar @$commentLines)
+        {
+        # Clear horizontal lines only if we're not in a code section.
+        if ($commentLines->[$index] =~ /^ *([^a-zA-Z0-9 ])\1{3,}$/ ||
+            ( length $commentLines->[$index] < 256 &&
+              $commentLines->[$index] =~ /^ *([^a-zA-Z0-9 ])\1*([^a-zA-Z0-9 ])\2{3,}([^a-zA-Z0-9 ])\3*$/ ) )
+        	{
+        	if (!$inCodeSection)
+        		{  $commentLines->[$index] = '';  }
+        	}
+
+        else
+        	{
+	        # Clear vertical lines.
+
+	        if ($leftSide == IS_UNIFORM)
+	            {
+	            # This works because every line should either start this way, be blank, or be the first line that doesn't start with a
+	            # symbol.
+	            $commentLines->[$index] =~ s/^ *([^a-zA-Z0-9 ])\1*//;
+	            };
+
+	        if ($rightSide == IS_UNIFORM)
+	            {
+	            $commentLines->[$index] =~ s/ *([^a-zA-Z0-9 ])\1*$//;
+	            };
+
+
+	        # Clear horizontal lines again if there were vertical lines.  This catches lines that were separated from the verticals by
+	        # whitespace.
+
+	        if (($leftSide == IS_UNIFORM || $rightSide == IS_UNIFORM) && !$inCodeSection)
+	            {
+	            $commentLines->[$index] =~ s/^ *([^a-zA-Z0-9 ])\1{3,}$//;
+	            $commentLines->[$index] =~ s/^ *([^a-zA-Z0-9 ])\1*([^a-zA-Z0-9 ])\2{3,}([^a-zA-Z0-9 ])\3*$//;
+	            };
+
+
+	        # Check for the start and end of code sections.  Note that this doesn't affect vertical line removal.
+
+	        if (!$inCodeSection &&
+	        	$commentLines->[$index] =~ /^ *\( *(?:(?:start|begin)? +)?(?:table|code|example|diagram) *\)$/i )
+	        	{
+	        	$inCodeSection = 1;
+	        	}
+	        elsif ($inCodeSection &&
+	        	    $commentLines->[$index] =~ /^ *\( *(?:end|finish|done)(?: +(?:table|code|example|diagram))? *\)$/i)
+	        	 {
+	        	 $inCodeSection = 0;
+	        	 }
+	        }
+
+
+        $index++;
+        };
+
+    };
+
+
+
+###############################################################################
+# Group: Processing Functions
+
+
+#
+#   Function: RepairPackages
+#
+#   Recalculates the packages for all comment topics using the auto-topics and the scope record.  Call this *before* calling
+#   <MergeAutoTopics()>.
+#
+#   Parameters:
+#
+#       autoTopics - A reference to the list of automatically generated <NaturalDocs::Parser::ParsedTopics>.
+#       scopeRecord - A reference to an array of <NaturalDocs::Languages::Advanced::ScopeChanges>.
+#
+sub RepairPackages #(autoTopics, scopeRecord)
+    {
+    my ($self, $autoTopics, $scopeRecord) = @_;
+
+    my $topicIndex = 0;
+    my $autoTopicIndex = 0;
+    my $scopeIndex = 0;
+
+    my $topic = $parsedFile[0];
+    my $autoTopic = $autoTopics->[0];
+    my $scopeChange = $scopeRecord->[0];
+
+    my $currentPackage;
+    my $inFakePackage;
+
+    while (defined $topic)
+        {
+        # First update the scope via the record if its defined and has the lowest line number.
+        if (defined $scopeChange &&
+            $scopeChange->LineNumber() <= $topic->LineNumber() &&
+            (!defined $autoTopic || $scopeChange->LineNumber() <= $autoTopic->LineNumber()) )
+            {
+            $currentPackage = $scopeChange->Scope();
+            $scopeIndex++;
+            $scopeChange = $scopeRecord->[$scopeIndex];  # Will be undef when past end.
+            $inFakePackage = undef;
+            }
+
+        # Next try to end a fake scope with an auto topic if its defined and has the lowest line number.
+        elsif (defined $autoTopic &&
+                $autoTopic->LineNumber() <= $topic->LineNumber())
+            {
+            if ($inFakePackage)
+                {
+                $currentPackage = $autoTopic->Package();
+                $inFakePackage = undef;
+                };
+
+            $autoTopicIndex++;
+            $autoTopic = $autoTopics->[$autoTopicIndex];  # Will be undef when past end.
+            }
+
+
+        # Finally try to handle the topic, since it has the lowest line number.  Check for Type() because headerless topics won't have
+        # one.
+        else
+            {
+            my $scope;
+            if ($topic->Type())
+                {  $scope = NaturalDocs::Topics->TypeInfo($topic->Type())->Scope();  }
+            else
+                {  $scope = ::SCOPE_NORMAL();  };
+
+            if ($scope == ::SCOPE_START() || $scope == ::SCOPE_END())
+                {
+                # They should already have the correct class and scope.
+                $currentPackage = $topic->Package();
+                $inFakePackage = 1;
+                }
+           else
+                {
+                # Fix the package of everything else.
+
+                # Note that the first function or variable topic to appear in a fake package will assume that package even if it turns out
+                # to be incorrect in the actual code, since the topic will come before the auto-topic.  This will be corrected in
+                # MergeAutoTopics().
+
+                $topic->SetPackage($currentPackage);
+                };
+
+            $topicIndex++;
+            $topic = $parsedFile[$topicIndex];  # Will be undef when past end.
+            };
+        };
+
+    };
+
+
+#
+#   Function: MergeAutoTopics
+#
+#   Merges the automatically generated topics into the file.  If an auto-topic matches an existing topic, it will have it's prototype
+#   and package transferred.  If it doesn't, the auto-topic will be inserted into the list unless
+#   <NaturalDocs::Settings->DocumentedOnly()> is set.  If an existing topic doesn't have a title, it's assumed to be a headerless
+#   comment and will be merged with the next auto-topic or discarded.
+#
+#   Parameters:
+#
+#       language - The <NaturalDocs::Languages::Base>-derived class for the file.
+#       autoTopics - A reference to the list of automatically generated topics.
+#
+sub MergeAutoTopics #(language, autoTopics)
+    {
+    my ($self, $language, $autoTopics) = @_;
+
+    my $topicIndex = 0;
+    my $autoTopicIndex = 0;
+
+    # Keys are topic types, values are existence hashrefs of titles.
+    my %topicsInLists;
+
+    while ($topicIndex < scalar @parsedFile && $autoTopicIndex < scalar @$autoTopics)
+        {
+        my $topic = $parsedFile[$topicIndex];
+        my $autoTopic = $autoTopics->[$autoTopicIndex];
+
+        my $cleanTitle = $topic->Title();
+        $cleanTitle =~ s/[\t ]*\([^\(]*$//;
+
+        # Add the auto-topic if it's higher in the file than the current topic.
+        if ($autoTopic->LineNumber() < $topic->LineNumber())
+            {
+            if (exists $topicsInLists{$autoTopic->Type()} &&
+                exists $topicsInLists{$autoTopic->Type()}->{$autoTopic->Title()})
+                {
+                # Remove it from the list so a second one with the same name will be added.
+                delete $topicsInLists{$autoTopic->Type()}->{$autoTopic->Title()};
+                }
+            elsif (!NaturalDocs::Settings->DocumentedOnly())
+                {
+                splice(@parsedFile, $topicIndex, 0, $autoTopic);
+                $topicIndex++;
+                };
+
+            $autoTopicIndex++;
+            }
+
+        # Remove a headerless topic if there's another topic between it and the next auto-topic.
+        elsif (!$topic->Title() && $topicIndex + 1 < scalar @parsedFile &&
+                $parsedFile[$topicIndex+1]->LineNumber() < $autoTopic->LineNumber())
+            {
+            splice(@parsedFile, $topicIndex, 1);
+            }
+
+        # Transfer information if we have a match or a headerless topic.
+        elsif ( !$topic->Title() || ($topic->Type() == $autoTopic->Type() && index($autoTopic->Title(), $cleanTitle) != -1) )
+            {
+            $topic->SetType($autoTopic->Type());
+            $topic->SetPrototype($autoTopic->Prototype());
+            $topic->SetUsing($autoTopic->Using());
+
+            if (!$topic->Title())
+                {  $topic->SetTitle($autoTopic->Title());  };
+
+            if (NaturalDocs::Topics->TypeInfo($topic->Type())->Scope() != ::SCOPE_START())
+                {  $topic->SetPackage($autoTopic->Package());  }
+            elsif ($autoTopic->Package() ne $topic->Package())
+                {
+                my @autoPackageIdentifiers = NaturalDocs::SymbolString->IdentifiersOf($autoTopic->Package());
+                my @packageIdentifiers = NaturalDocs::SymbolString->IdentifiersOf($topic->Package());
+
+                while (scalar @autoPackageIdentifiers && $autoPackageIdentifiers[-1] eq $packageIdentifiers[-1])
+                    {
+                    pop @autoPackageIdentifiers;
+                    pop @packageIdentifiers;
+                    };
+
+                if (scalar @autoPackageIdentifiers)
+                    {  $topic->SetPackage( NaturalDocs::SymbolString->Join(@autoPackageIdentifiers) );  };
+                };
+
+            $topicIndex++;
+            $autoTopicIndex++;
+            }
+
+        # Extract topics in lists.
+        elsif ($topic->IsList())
+            {
+            if (!exists $topicsInLists{$topic->Type()})
+                {  $topicsInLists{$topic->Type()} = { };  };
+
+            my $body = $topic->Body();
+
+            while ($body =~ /<ds>([^<]+)<\/ds>/g)
+                {  $topicsInLists{$topic->Type()}->{NaturalDocs::NDMarkup->RestoreAmpChars($1)} = 1;  };
+
+            $topicIndex++;
+            }
+
+        # Otherwise there's no match.  Skip the topic.  The auto-topic will be added later.
+        else
+            {
+            $topicIndex++;
+            }
+        };
+
+    # Add any auto-topics remaining.
+    if (!NaturalDocs::Settings->DocumentedOnly())
+    	{
+	    while ($autoTopicIndex < scalar @$autoTopics)
+	        {
+	        my $autoTopic = $autoTopics->[$autoTopicIndex];
+
+	        if (exists $topicsInLists{$autoTopic->Type()} &&
+	            exists $topicsInLists{$autoTopic->Type()}->{$autoTopic->Title()})
+	            {
+	            # Remove it from the list so a second one with the same name will be added.
+	            delete $topicsInLists{$autoTopic->Type()}->{$autoTopic->Title()};
+	            }
+	        else
+	            {
+	            push(@parsedFile, $autoTopic);
+	            };
+
+	        $autoTopicIndex++;
+	        };
+        };
+   };
+
+
+#
+#   Function: RemoveRemainingHeaderlessTopics
+#
+#   After <MergeAutoTopics()> is done, this function removes any remaining headerless topics from the file.  If they don't merge
+#   into anything, they're not valid topics.
+#
+sub RemoveRemainingHeaderlessTopics
+    {
+    my ($self) = @_;
+
+    my $index = 0;
+    while ($index < scalar @parsedFile)
+        {
+        if ($parsedFile[$index]->Title())
+            {  $index++;  }
+        else
+            {  splice(@parsedFile, $index, 1);  };
+        };
+    };
+
+
+#
+#   Function: MakeAutoGroups
+#
+#   Creates group topics for files that do not have them.
+#
+sub MakeAutoGroups
+    {
+    my ($self) = @_;
+
+    # No groups only one topic.
+    if (scalar @parsedFile < 2)
+        {  return;  };
+
+    my $index = 0;
+    my $startStretch = 0;
+
+    # Skip the first entry if its the page title.
+    if (NaturalDocs::Topics->TypeInfo( $parsedFile[0]->Type() )->PageTitleIfFirst())
+        {
+        $index = 1;
+        $startStretch = 1;
+        };
+
+    # Make auto-groups for each stretch between scope-altering topics.
+    while ($index < scalar @parsedFile)
+        {
+        my $scope = NaturalDocs::Topics->TypeInfo($parsedFile[$index]->Type())->Scope();
+
+        if ($scope == ::SCOPE_START() || $scope == ::SCOPE_END())
+            {
+            if ($index > $startStretch)
+                {  $index += $self->MakeAutoGroupsFor($startStretch, $index);  };
+
+            $startStretch = $index + 1;
+            };
+
+        $index++;
+        };
+
+    if ($index > $startStretch)
+        {  $self->MakeAutoGroupsFor($startStretch, $index);  };
+    };
+
+
+#
+#   Function: MakeAutoGroupsFor
+#
+#   Creates group topics for sections of files that do not have them.  A support function for <MakeAutoGroups()>.
+#
+#   Parameters:
+#
+#       startIndex - The index to start at.
+#       endIndex - The index to end at.  Not inclusive.
+#
+#   Returns:
+#
+#       The number of group topics added.
+#
+sub MakeAutoGroupsFor #(startIndex, endIndex)
+    {
+    my ($self, $startIndex, $endIndex) = @_;
+
+    # No groups if any are defined already.
+    for (my $i = $startIndex; $i < $endIndex; $i++)
+        {
+        if ($parsedFile[$i]->Type() eq ::TOPIC_GROUP())
+            {  return 0;  };
+        };
+
+
+    use constant COUNT => 0;
+    use constant TYPE => 1;
+    use constant SECOND_TYPE => 2;
+    use constant SIZE => 3;
+
+    # This is an array of ( count, type, secondType ) triples.  Count and Type will always be filled in; count is the number of
+    # consecutive topics of type.  On the second pass, if small groups are combined secondType will be filled in.  There will not be
+    # more than two types per group.
+    my @groups;
+    my $groupIndex = 0;
+
+
+    # First pass: Determine all the groups.
+
+    my $i = $startIndex;
+    my $currentType;
+
+    while ($i < $endIndex)
+        {
+        if (!defined $currentType || ($parsedFile[$i]->Type() ne $currentType && $parsedFile[$i]->Type() ne ::TOPIC_GENERIC()) )
+            {
+            if (defined $currentType)
+                {  $groupIndex += SIZE;  };
+
+            $currentType = $parsedFile[$i]->Type();
+
+            $groups[$groupIndex + COUNT] = 1;
+            $groups[$groupIndex + TYPE] = $currentType;
+            }
+        else
+            {  $groups[$groupIndex + COUNT]++;  };
+
+        $i++;
+        };
+
+
+    # Second pass: Combine groups based on "noise".  Noise means types go from A to B to A at least once, and there are at least
+    # two groups in a row with three or less, and at least one of those groups is two or less.  So 3, 3, 3 doesn't count as noise, but
+    # 3, 2, 3 does.
+
+    $groupIndex = 0;
+
+    # While there are at least three groups left...
+    while ($groupIndex < scalar @groups - (2 * SIZE))
+        {
+        # If the group two places in front of this one has the same type...
+        if ($groups[$groupIndex + (2 * SIZE) + TYPE] eq $groups[$groupIndex + TYPE])
+            {
+            # It means we went from A to B to A, which partially qualifies as noise.
+
+            my $firstType = $groups[$groupIndex + TYPE];
+            my $secondType = $groups[$groupIndex + SIZE + TYPE];
+
+            if (NaturalDocs::Topics->TypeInfo($firstType)->CanGroupWith($secondType) ||
+                NaturalDocs::Topics->TypeInfo($secondType)->CanGroupWith($firstType))
+                {
+                my $hasNoise;
+
+                my $hasThrees;
+                my $hasTwosOrOnes;
+
+                my $endIndex = $groupIndex;
+
+                while ($endIndex < scalar @groups &&
+                         ($groups[$endIndex + TYPE] eq $firstType || $groups[$endIndex + TYPE] eq $secondType))
+                    {
+                    if ($groups[$endIndex + COUNT] > 3)
+                        {
+                        # They must be consecutive to count.
+                        $hasThrees = 0;
+                        $hasTwosOrOnes = 0;
+                        }
+                    elsif ($groups[$endIndex + COUNT] == 3)
+                        {
+                        $hasThrees = 1;
+
+                        if ($hasTwosOrOnes)
+                            {  $hasNoise = 1;  };
+                        }
+                    else # < 3
+                        {
+                        if ($hasThrees || $hasTwosOrOnes)
+                            {  $hasNoise = 1;  };
+
+                        $hasTwosOrOnes = 1;
+                        };
+
+                    $endIndex += SIZE;
+                    };
+
+                if (!$hasNoise)
+                    {
+                    $groupIndex = $endIndex - SIZE;
+                    }
+                else # hasNoise
+                    {
+                    $groups[$groupIndex + SECOND_TYPE] = $secondType;
+
+                    for (my $noiseIndex = $groupIndex + SIZE; $noiseIndex < $endIndex; $noiseIndex += SIZE)
+                        {
+                        $groups[$groupIndex + COUNT] += $groups[$noiseIndex + COUNT];
+                        };
+
+                    splice(@groups, $groupIndex + SIZE, $endIndex - $groupIndex - SIZE);
+
+                    $groupIndex += SIZE;
+                    };
+                }
+
+            else # They can't group together
+                {
+                $groupIndex += SIZE;
+                };
+            }
+
+        else
+            {  $groupIndex += SIZE;  };
+        };
+
+
+    # Finally, create group topics for the parsed file.
+
+    $groupIndex = 0;
+    $i = $startIndex;
+
+    while ($groupIndex < scalar @groups)
+        {
+        if ($groups[$groupIndex + TYPE] ne ::TOPIC_GENERIC())
+            {
+            my $topic = $parsedFile[$i];
+            my $title = NaturalDocs::Topics->NameOfType($groups[$groupIndex + TYPE], 1);
+
+            if (defined $groups[$groupIndex + SECOND_TYPE])
+                {  $title .= ' and ' . NaturalDocs::Topics->NameOfType($groups[$groupIndex + SECOND_TYPE], 1);  };
+
+            splice(@parsedFile, $i, 0, NaturalDocs::Parser::ParsedTopic->New(::TOPIC_GROUP(),
+                                                                                                            $title,
+                                                                                                            $topic->Package(), $topic->Using(),
+                                                                                                            undef, undef, undef,
+                                                                                                            $topic->LineNumber()) );
+            $i++;
+            };
+
+        $i += $groups[$groupIndex + COUNT];
+        $groupIndex += SIZE;
+        };
+
+    return (scalar @groups / SIZE);
+    };
+
+
+#
+#   Function: AddToClassHierarchy
+#
+#   Adds any class topics to the class hierarchy, since they may not have been called with <OnClass()> if they didn't match up to
+#   an auto-topic.
+#
+sub AddToClassHierarchy
+    {
+    my ($self) = @_;
+
+    foreach my $topic (@parsedFile)
+        {
+        if ($topic->Type() && NaturalDocs::Topics->TypeInfo( $topic->Type() )->ClassHierarchy())
+            {
+            if ($topic->IsList())
+                {
+                my $body = $topic->Body();
+
+                while ($body =~ /<ds>([^<]+)<\/ds>/g)
+                    {
+                    $self->OnClass( NaturalDocs::SymbolString->FromText( NaturalDocs::NDMarkup->RestoreAmpChars($1) ) );
+                    };
+                }
+            else
+                {
+                $self->OnClass($topic->Package());
+                };
+            };
+        };
+    };
+
+
+#
+#   Function: AddPackageDelineators
+#
+#   Adds section and class topics to make sure the package is correctly represented in the documentation.  Should be called last in
+#   this process.
+#
+sub AddPackageDelineators
+    {
+    my ($self) = @_;
+
+    my $index = 0;
+    my $currentPackage;
+
+    # Values are the arrayref [ title, type ];
+    my %usedPackages;
+
+    while ($index < scalar @parsedFile)
+        {
+        my $topic = $parsedFile[$index];
+
+        if ($topic->Package() ne $currentPackage)
+            {
+            $currentPackage = $topic->Package();
+            my $scopeType = NaturalDocs::Topics->TypeInfo($topic->Type())->Scope();
+
+            if ($scopeType == ::SCOPE_START())
+                {
+                $usedPackages{$currentPackage} = [ $topic->Title(), $topic->Type() ];
+                }
+            elsif ($scopeType == ::SCOPE_END())
+                {
+                my $newTopic;
+
+                if (!defined $currentPackage)
+                    {
+                    $newTopic = NaturalDocs::Parser::ParsedTopic->New(::TOPIC_SECTION(), 'Global',
+                                                                                                   undef, undef,
+                                                                                                   undef, undef, undef,
+                                                                                                   $topic->LineNumber(), undef);
+                    }
+                else
+                    {
+                    my ($title, $body, $summary, $type);
+                    my @packageIdentifiers = NaturalDocs::SymbolString->IdentifiersOf($currentPackage);
+
+                    if (exists $usedPackages{$currentPackage})
+                        {
+                        $title = $usedPackages{$currentPackage}->[0];
+                        $type = $usedPackages{$currentPackage}->[1];
+                        $body = '<p>(continued)</p>';
+                        $summary = '(continued)';
+                        }
+                    else
+                        {
+                        $title = join($language->PackageSeparator(), @packageIdentifiers);
+                        $type = ::TOPIC_CLASS();
+
+                        # Body and summary stay undef.
+
+                        $usedPackages{$currentPackage} = $title;
+                        };
+
+                    my @titleIdentifiers = NaturalDocs::SymbolString->IdentifiersOf( NaturalDocs::SymbolString->FromText($title) );
+                    for (my $i = 0; $i < scalar @titleIdentifiers; $i++)
+                        {  pop @packageIdentifiers;  };
+
+                    $newTopic = NaturalDocs::Parser::ParsedTopic->New($type, $title,
+                                                                                                   NaturalDocs::SymbolString->Join(@packageIdentifiers), undef,
+                                                                                                   undef, $summary, $body,
+                                                                                                   $topic->LineNumber(), undef);
+                    }
+
+                splice(@parsedFile, $index, 0, $newTopic);
+                $index++;
+                }
+            };
+
+        $index++;
+        };
+    };
+
+
+#
+#   Function: BreakLists
+#
+#   Breaks list topics into individual topics.
+#
+sub BreakLists
+    {
+    my $self = shift;
+
+    my $index = 0;
+
+    while ($index < scalar @parsedFile)
+        {
+        my $topic = $parsedFile[$index];
+
+        if ($topic->IsList() && NaturalDocs::Topics->TypeInfo( $topic->Type() )->BreakLists())
+            {
+            my $body = $topic->Body();
+
+            my @newTopics;
+            my $newBody;
+
+            my $bodyIndex = 0;
+
+            for (;;)
+                {
+                my $startList = index($body, '<dl>', $bodyIndex);
+
+                if ($startList == -1)
+                    {  last;  };
+
+                $newBody .= substr($body, $bodyIndex, $startList - $bodyIndex);
+
+                my $endList = index($body, '</dl>', $startList);
+                my $listBody = substr($body, $startList, $endList - $startList);
+
+                while ($listBody =~ /<ds>([^<]+)<\/ds><dd>(.*?)<\/dd>/g)
+                    {
+                    my ($symbol, $description) = ($1, $2);
+
+                    push @newTopics, NaturalDocs::Parser::ParsedTopic->New( $topic->Type(), $symbol, $topic->Package(),
+                                                                                                            $topic->Using(), undef,
+                                                                                                            $self->GetSummaryFromDescriptionList($description),
+                                                                                                            '<p>' . $description .  '</p>', $topic->LineNumber(),
+                                                                                                            undef );
+                    };
+
+                $bodyIndex = $endList + 5;
+                };
+
+            $newBody .= substr($body, $bodyIndex);
+
+            # Remove trailing headings.
+            $newBody =~ s/(?:<h>[^<]+<\/h>)+$//;
+
+            # Remove empty headings.
+            $newBody =~ s/(?:<h>[^<]+<\/h>)+(<h>[^<]+<\/h>)/$1/g;
+
+            if ($newBody)
+                {
+                unshift @newTopics, NaturalDocs::Parser::ParsedTopic->New( ::TOPIC_GROUP(), $topic->Title(), $topic->Package(),
+                                                                                                          $topic->Using(), undef,
+                                                                                                          $self->GetSummaryFromBody($newBody), $newBody,
+                                                                                                          $topic->LineNumber(), undef );
+                };
+
+            splice(@parsedFile, $index, 1, @newTopics);
+
+            $index += scalar @newTopics;
+            }
+
+        else # not a list
+            {  $index++;  };
+        };
+    };
+
+
+#
+#   Function: GetSummaryFromBody
+#
+#   Returns the summary text from the topic body.
+#
+#   Parameters:
+#
+#       body - The complete topic body, in <NDMarkup>.
+#
+#   Returns:
+#
+#       The topic summary, or undef if none.
+#
+sub GetSummaryFromBody #(body)
+    {
+    my ($self, $body) = @_;
+
+    my $summary;
+
+    # Extract the first sentence from the leading paragraph, if any.  We'll tolerate a single header beforehand, but nothing else.
+
+    if ($body =~ /^(?:<h>[^<]*<\/h>)?<p>(.*?)(<\/p>|[\.\!\?](?:[\)\}\'\ ]|&quot;|&gt;))/x)
+        {
+        $summary = $1;
+
+        if ($2 ne '</p>')
+            {  $summary .= $2;  };
+        };
+
+    return $summary;
+    };
+
+
+#
+#   Function: GetSummaryFromDescriptionList
+#
+#   Returns the summary text from a description list entry.
+#
+#   Parameters:
+#
+#       description - The description in <NDMarkup>.  Should be the content between the <dd></dd> tags only.
+#
+#   Returns:
+#
+#       The description summary, or undef if none.
+#
+sub GetSummaryFromDescriptionList #(description)
+    {
+    my ($self, $description) = @_;
+
+    my $summary;
+
+    if ($description =~ /^(.*?)($|[\.\!\?](?:[\)\}\'\ ]|&quot;|&gt;))/)
+        {  $summary = $1 . $2;  };
+
+    return $summary;
+    };
+
+
+1;