added doc tool

1 files changed, 400 insertions, 0 deletions

diff --git a/docs/tool/NaturalDocs b/docs/tool/NaturalDocs
new file mode 100755
index 00000000..b5ddaea1
--- /dev/null
+++ b/docs/tool/NaturalDocs
@@ -0,0 +1,400 @@
+#!/usr/bin/perl
+
+=begin nd
+
+    Script: NaturalDocs
+    ___________________________________________________________________________
+
+    Version 1.4
+
+    Copyright (C) 2003-2008 Greg Valure
+
+    http://www.naturaldocs.org
+
+
+    About: License
+
+        Licensed under the GNU General Public License
+
+        This program is free software; you can redistribute it and/or modify
+        it under the terms of the GNU General Public License as published by
+        the Free Software Foundation; either version 2 of the License, or
+        (at your option) any later version.
+
+        This program is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        GNU General Public License for more details.
+
+        You should have received a copy of the GNU General Public License
+        along with this program; if not, visit http://www.gnu.org/licenses/gpl.txt
+        or write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+        Boston, MA  02111-1307  USA.
+
+
+    Topic: Code Conventions
+
+        - Every package function is called with an arrow operator.  It's needed for inheritance in some places, and consistency
+         when it's not.
+
+        - No constant will ever be zero or undef.  Those are reserved so any piece of code can allow a "none of the above" option
+         and not worry about conflicts with an existing value.
+
+        - Existence hashes are hashes where the value doesn't matter.  It acts more as a set, where the existence of the key is
+         the significant part.
+
+
+    Topic: File Format Conventions
+
+        - All integers appear in big-endian format.  So a UInt16 should be handled with a 'n' in pack and unpack, not with a 'S'.
+
+        - AString16's are a big-endian UInt16 followed by that many ASCII characters.  A null-terminator is not stored.
+
+        - If a higher-level type is described in a file format, that means the loading and saving format is handled by that package.
+         For example, if you see <SymbolString> in the format, that means <NaturalDocs::SymbolString->ToBinaryFile()> and
+         <NaturalDocs::SymbolString->FromBinaryFile()> are used to manipulate it, and the underlying format should be treated
+         as opaque.
+
+=cut
+
+
+use strict;
+use integer;
+
+use 5.005;  # When File::Spec was included by default
+
+use English '-no_match_vars';
+
+use FindBin;
+use lib "$FindBin::RealBin/Modules";
+
+sub INIT
+    {
+    # This function is just here so that when I start the debugger, it doesn't open a new file.  Normally it would jump to an INIT
+    # function in some other file since that's the first piece of code to execute.
+    };
+
+
+use NaturalDocs::Constants;
+use NaturalDocs::Version;
+use NaturalDocs::File;
+use NaturalDocs::Error;
+
+use NaturalDocs::ConfigFile;
+use NaturalDocs::BinaryFile;
+use NaturalDocs::StatusMessage;
+use NaturalDocs::SymbolString;
+use NaturalDocs::ReferenceString;
+use NaturalDocs::NDMarkup;
+
+use NaturalDocs::Settings;
+use NaturalDocs::Topics;
+use NaturalDocs::Languages;
+use NaturalDocs::Project;
+use NaturalDocs::Menu;
+use NaturalDocs::SymbolTable;
+use NaturalDocs::ClassHierarchy;
+use NaturalDocs::SourceDB;
+use NaturalDocs::ImageReferenceTable;
+use NaturalDocs::Parser;
+use NaturalDocs::Builder;
+
+
+
+###############################################################################
+#
+#   Group: Basic Types
+#
+#   Types used throughout the program.  As Perl is a weakly-typed language unless you box things into objects, these types are
+#   for documentation purposes and are not enforced.
+#
+#
+#   Type: FileName
+#
+#   A string representing the absolute, platform-dependent path to a file.  Relative file paths are no longer in use anywhere in the
+#   program.  All path manipulation should be done through <NaturalDocs::File>.
+#
+#
+#   Type: VersionInt
+#
+#   A comparable integer representing a version number.  Converting them to and from text and binary should be handled by
+#   <NaturalDocs::Version>.
+#
+#
+#   Type: SymbolString
+#
+#   A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.  All symbols
+#   must be retrieved from plain text via <NaturalDocs::SymbolString->FromText()> so that the separation and normalization is
+#   always consistent.  SymbolStrings are comparable via string compare functions and are sortable.
+#
+#
+#   Type: ReferenceString
+#
+#   All the information about a reference that makes it unique encoded into a string.  This includes the <SymbolString> of the
+#   reference, the scope <SymbolString> it appears in, the scope <SymbolStrings> it has access to via "using", and the
+#   <ReferenceType>.  This is done because if any of those parameters change, it needs to be treated as a completely separate
+#   reference.
+#
+
+
+
+###############################################################################
+# Group: Support Functions
+# General functions that are used throughout the program, and that don't really fit anywhere else.
+
+
+#
+#   Function: StringCompare
+#
+#   Compares two strings so that the result is good for proper sorting.  A proper sort orders the characters as
+#   follows:
+#
+#   - End of string.
+#   - Whitespace.  Line break-tab-space.
+#   - Symbols, which is anything not included in the other entries.
+#   - Numbers, 0-9.
+#   - Letters, case insensitive except to break ties.
+#
+#   If you use cmp instead of this function, the result would go by ASCII/Unicode values which would place certain symbols
+#   between letters and numbers instead of having them all grouped together.  Also, you would have to choose between case
+#   sensitivity or complete case insensitivity, in which ties are broken arbitrarily.
+#
+#   Returns:
+#
+#   Like cmp, it returns zero if A and B are equal, a positive value if A is greater than B, and a negative value if A is less than B.
+#
+sub StringCompare #(a, b)
+    {
+    my ($a, $b) = @_;
+
+    if (!defined $a)
+        {
+        if (!defined $b)
+            {  return 0;  }
+        else
+            {  return -1;  };
+        }
+    elsif (!defined $b)
+        {
+        return 1;
+        };
+
+    my $translatedA = lc($a);
+    my $translatedB = lc($b);
+
+    $translatedA =~ tr/\n\r\t 0-9a-z/\x01\x02\x03\x04\xDB-\xFE/;
+    $translatedB =~ tr/\n\r\t 0-9a-z/\x01\x02\x03\x04\xDB-\xFE/;
+
+    my $result = $translatedA cmp $translatedB;
+
+    if ($result == 0)
+        {
+        # Break the tie by comparing their case.  Lowercase before uppercase.
+
+        # If statement just to keep everything theoretically kosher, even though in practice we don't need this.
+        if (ord('A') > ord('a'))
+            {  return ($a cmp $b);  }
+        else
+            {  return ($b cmp $a);  };
+        }
+    else
+        {  return $result;  };
+    };
+
+
+#
+#   Function: ShortenToMatchStrings
+#
+#   Compares two arrayrefs and shortens the first array to only contain shared entries.  Assumes all entries are strings.
+#
+#   Parameters:
+#
+#       sharedArrayRef - The arrayref that will be shortened to only contain common elements.
+#       compareArrayRef - The arrayref to match.
+#
+sub ShortenToMatchStrings #(sharedArrayRef, compareArrayRef)
+    {
+    my ($sharedArrayRef, $compareArrayRef) = @_;
+
+    my $index = 0;
+
+    while ($index < scalar @$sharedArrayRef && $index < scalar @$compareArrayRef &&
+             $sharedArrayRef->[$index] eq $compareArrayRef->[$index])
+        {  $index++;  };
+
+    if ($index < scalar @$sharedArrayRef)
+        {  splice(@$sharedArrayRef, $index);  };
+    };
+
+
+#
+#   Function: XChomp
+#
+#   A cross-platform chomp function.  Regular chomp fails when parsing Windows-format line breaks on a Unix platform.  It
+#   leaves the /r on, which screws everything up.  This does not.
+#
+#   Parameters:
+#
+#       lineRef - A *reference* to the line to chomp.
+#
+sub XChomp #(lineRef)
+    {
+    my $lineRef = shift;
+    $$lineRef =~ s/[\n\r]+$//;
+    };
+
+
+#
+#   Function: FindFirstSymbol
+#
+#   Searches a string for a number of symbols to see which appears first.
+#
+#   Parameters:
+#
+#       string - The string to search.
+#       symbols - An arrayref of symbols to look for.
+#       index - The index to start at, if any.
+#
+#   Returns:
+#
+#       The array ( index, symbol ).
+#
+#       index - The index the first symbol appears at, or -1 if none appear.
+#       symbol - The symbol that appeared, or undef if none.
+#
+sub FindFirstSymbol #(string, symbols, index)
+    {
+    my ($string, $symbols, $index) = @_;
+
+    if (!defined $index)
+        {  $index = 0;  };
+
+    my $lowestIndex = -1;
+    my $lowestSymbol;
+
+    foreach my $symbol (@$symbols)
+        {
+        my $testIndex = index($string, $symbol, $index);
+
+        if ($testIndex != -1 && ($lowestIndex == -1 || $testIndex < $lowestIndex))
+            {
+            $lowestIndex = $testIndex;
+            $lowestSymbol = $symbol;
+            };
+        };
+
+    return ($lowestIndex, $lowestSymbol);
+    };
+
+
+
+
+###############################################################################
+#
+#   Main Code
+#
+#   The order in which functions are called here is critically important.  Read the "Usage and Dependencies" sections of all the
+#   packages before even thinking about rearranging these.
+#
+
+
+eval {
+
+    # Check that our required packages are okay.
+
+    NaturalDocs::File->CheckCompatibility();
+
+
+    # Almost everything requires Settings to be initialized.
+
+    NaturalDocs::Settings->Load();
+
+
+    NaturalDocs::Project->LoadConfigFileInfo();
+
+    NaturalDocs::Topics->Load();
+    NaturalDocs::Languages->Load();
+
+
+    # Migrate from the old file names that were used prior to 1.14.
+
+    NaturalDocs::Project->MigrateOldFiles();
+
+
+    if (!NaturalDocs::Settings->IsQuiet())
+        {  print "Finding files and detecting changes...\n";  };
+
+    NaturalDocs::Project->LoadSourceFileInfo();
+    NaturalDocs::Project->LoadImageFileInfo();
+
+    # Register SourceDB extensions.  Order is important.
+    NaturalDocs::ImageReferenceTable->Register();
+
+    NaturalDocs::SymbolTable->Load();
+    NaturalDocs::ClassHierarchy->Load();
+    NaturalDocs::SourceDB->Load();
+
+    NaturalDocs::SymbolTable->Purge();
+    NaturalDocs::ClassHierarchy->Purge();
+    NaturalDocs::SourceDB->PurgeDeletedSourceFiles();
+
+
+    # Parse any supported files that have changed.
+
+    my $filesToParse = NaturalDocs::Project->FilesToParse();
+    my $amount = scalar keys %$filesToParse;
+
+    if ($amount > 0)
+        {
+        NaturalDocs::StatusMessage->Start('Parsing ' . $amount . ' file' . ($amount > 1 ? 's' : '') . '...', $amount);
+
+        foreach my $file (keys %$filesToParse)
+            {
+            NaturalDocs::Parser->ParseForInformation($file);
+            NaturalDocs::StatusMessage->CompletedItem();
+            };
+        };
+
+
+    # The symbol table is now fully resolved, so we can reduce its memory footprint.
+
+    NaturalDocs::SymbolTable->PurgeResolvingInfo();
+
+
+    # Load and update the menu file.  We need to do this after parsing so when it is updated, it will detect files where the
+    # default menu title has changed and files that have added or deleted Natural Docs content.
+
+    NaturalDocs::Menu->LoadAndUpdate();
+
+
+    # Build any files that need it.  This needs to be run regardless of whether there are any files to build.  It will handle its own
+    # output messages.
+
+    NaturalDocs::Builder->Run();
+
+
+    # Write the changes back to disk.
+
+    NaturalDocs::Menu->Save();
+    NaturalDocs::Project->SaveImageFileInfo();
+    NaturalDocs::Project->SaveSourceFileInfo();
+    NaturalDocs::SymbolTable->Save();
+    NaturalDocs::ClassHierarchy->Save();
+    NaturalDocs::SourceDB->Save();
+    NaturalDocs::Settings->Save();
+    NaturalDocs::Topics->Save();
+    NaturalDocs::Languages->Save();
+
+    # Must be done last.
+    NaturalDocs::Project->SaveConfigFileInfo();
+
+    if (!NaturalDocs::Settings->IsQuiet())
+        {  print "Done.\n";  };
+
+};
+
+if ($EVAL_ERROR)  # Oops.
+    {
+    NaturalDocs::Error->HandleDeath();
+    };
+