diff --git a/HeaderDoc-1.6-strict.dtd b/HeaderDoc-1.6-strict.dtd new file mode 100644 index 0000000..49e524b --- /dev/null +++ b/HeaderDoc-1.6-strict.dtd @@ -0,0 +1,476 @@ + + + + + + + + + + + + + + + + + + + + + +%htmlDTD; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/HeaderDoc-1.6.dtd b/HeaderDoc-1.6.dtd new file mode 100644 index 0000000..a5e3a7f --- /dev/null +++ b/HeaderDoc-1.6.dtd @@ -0,0 +1,687 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Modules/HeaderDoc/APIOwner.pm b/Modules/HeaderDoc/APIOwner.pm index eff71e7..278ba72 100644 --- a/Modules/HeaderDoc/APIOwner.pm +++ b/Modules/HeaderDoc/APIOwner.pm @@ -3,7 +3,7 @@ # Class name: APIOwner # Synopsis: Abstract superclass for Header and OO structures # -# Last Updated: $Date: 2014/02/14 17:55:29 $ +# Last Updated: $Date: 2014/02/25 14:46:13 $ # # Method additions by SKoT McDonald Aug 2001 # @@ -229,7 +229,7 @@ use vars qw(@ISA); # In the git repository, contains the number of seconds since # January 1, 1970. # */ -$HeaderDoc::APIOwner::VERSION = '$Revision: 1392429329 $'; +$HeaderDoc::APIOwner::VERSION = '$Revision: 1393368373 $'; my $addToDebug = 0; @@ -4673,6 +4673,33 @@ sub _getFunctionXMLDetailString { return $contentString; } +# /*! +# @abstract +# Returns the XML content string for classes in this class or header. +# @param self +# The APIOwner object. +# @discussion +# Called by {@link _getXMLPageString}. +# */ +sub _getEmbeddedClassXMLDetailString { + my $self = shift; + my $classObjsRef = shift; + my @classObjs = @{$classObjsRef}; + my $contentString = ""; + + my @tempobjs = (); + if (!$self->unsorted()) { + @tempobjs = sort objName @classObjs; + } else { + @tempobjs = @classObjs; + } + foreach my $obj (@tempobjs) { + # print STDERR "outputting class ".$obj->name."."; + my $documentationBlock = $obj->XMLdocumentationBlock(); + $contentString .= $documentationBlock; + } + return $contentString; +} # /*! # @abstract @@ -5735,8 +5762,8 @@ sub _createXMLOutputFile { $doctype = "framework"; } - # print OUTFILE "\n"; - print OUTFILE "\n"; + # print OUTFILE "\n"; + print OUTFILE "\n"; # print OUTFILE "
"; # print OUTFILE "$heading\n"; diff --git a/Modules/HeaderDoc/HeaderElement.pm b/Modules/HeaderDoc/HeaderElement.pm index 96cdc09..6e4f9dc 100644 --- a/Modules/HeaderDoc/HeaderElement.pm +++ b/Modules/HeaderDoc/HeaderElement.pm @@ -3,7 +3,7 @@ # Class name: HeaderElement # Synopsis: Root class for Function, Typedef, Constant, etc. -- used by HeaderDoc. # -# Last Updated: $Date: 2013/05/14 15:29:11 $ +# Last Updated: $Date: 2014/02/25 15:59:56 $ # # Copyright (c) 1999-2004 Apple Computer, Inc. All rights reserved. # @@ -340,6 +340,17 @@ # {@link //apple_ref/perl/cl/HeaderDoc::Var Var} objects. # @var XMLTHROWS # A copy of the value in THROWS with XML formatting. +# @var AS_CLASS_SELF +# A CPPClass object cloned from the current function object that holds +# any scripts that are nested within the function. See +# {@link cloneAppleScriptFunctionContents} and {@link processAppleScriptFunctionContents} +# for more information. +# @var ASCONTENTSPROCESSED +# Set to 1 after the {@link processAppleScriptFunctionContents} method runs. +# for more information. +# @var PARSEDPSEUDOCLASSNAME +# The name of the directory where the contents from any classes within the {@link AS_CLASS_SELF} +# container are written. # */ package HeaderDoc::HeaderElement; @@ -356,6 +367,16 @@ use Encode qw(encode decode); use Devel::Peek; +my $isMacOS; +my $pathSeparator; +if ($^O =~ /MacOS/io) { + $pathSeparator = ":"; + $isMacOS = 1; +} else { + $pathSeparator = "/"; + $isMacOS = 0; +} + # /*! # @abstract # The revision control revision number for this module. @@ -363,7 +384,7 @@ use Devel::Peek; # In the git repository, contains the number of seconds since # January 1, 1970. # */ -$HeaderDoc::HeaderElement::VERSION = '$Revision: 1368570551 $'; +$HeaderDoc::HeaderElement::VERSION = '$Revision: 1393372796 $'; # /*! # @abstract @@ -1116,7 +1137,7 @@ sub name { my($class) = ref($self) || $self; - print STDERR "$class\n" if ($localDebug); + print STDERR "IN NAME: $class\n" if ($localDebug); if (@_) { my $name = shift; @@ -4242,6 +4263,7 @@ sub declarationInHTML { # */ sub parseTree { my $self = shift; + my $localDebug = 0; if (@_) { my $parsetree = shift; @@ -4249,6 +4271,18 @@ sub parseTree { $self->addParseTree($parsetree); } $self->{PARSETREE} = $parsetree; + + my $class = ref($self) || $self; + if ($self->lang eq "applescript" && $class eq "HeaderDoc::Function") { + if (!$self->{AS_CLASS_SELF}) { + $self->cloneAppleScriptFunctionContents(); + } + if ($localDebug) { + print STDERR "ADDING PARSE TREE FOR $self\n"; + bless($parsetree, "HeaderDoc::ParseTree"); + ${$parsetree}->dbprint(); + } + } } return $self->{PARSETREE}; } @@ -5155,6 +5189,18 @@ sub documentationBlock if ($self->isInternal() && !$HeaderDoc::document_internal) { return ""; } + my @embeddedClasses = (); + my $class_self = undef; + if ($self->lang eq "applescript" && $class eq "HeaderDoc::Function") { + if (!$self->{ASCONTENTSPROCESSED}) { + $class_self = $self->processAppleScriptFunctionContents(); + my @classes = $class_self->classes(); + foreach my $obj (@classes) { + push(@embeddedClasses, $obj); + } + } + } + # print STDERR "GOTHERE\n"; # Only use this style for API Owners. @@ -5518,6 +5564,48 @@ sub documentationBlock $contentString .= "\n"; } } + if (@embeddedClasses) { + $showDiscussionHeading = 1; + $contentString .= "
Embedded Classes
\n"; + $contentString .= "
\n"; + $contentString .= "
\n"; + # $contentString .= "\n"; + # $contentString .= "\n"; + foreach my $element (@embeddedClasses) { + my $cName = $element->name(); + + # print STDERR "EMBEDDED CLASS: $cName\n"; + + my $cDesc = $element->discussion(); + # my $uid = "//$apiUIDPrefix/c/econst/$cName"; + # registerUID($uid); + my $uid = $element->apiuid(); # "econst"); + + my $safeName = $cName; + $safeName = &safeName(filename => $cName); + + my $url = $class_self->{PARSEDPSEUDOCLASSNAME}.$pathSeparator."Classes".$pathSeparator.$safeName.$pathSeparator."index.html"; + + my $target = "doc"; + my $classAsComposite = $HeaderDoc::ClassAsComposite; + # if ($class eq "HeaderDoc::Header") { $classAsComposite = 0; } + + if ($composite && !$classAsComposite) { $classAsComposite = 1; $target = "_top"; } + if ($element->isAPIOwner()) { + $target = "_top"; + $classAsComposite = 0; + } + + if ($HeaderDoc::use_iframes) { + $target = "_top"; + } + + # $contentString .= "\n"; + $contentString .= "
$cName
$cDesc
\n"; + } + # $contentString .= "
NameDescription
$cName$cDesc
\n
\n"; + $contentString .= "\n\n"; + } if (@constants) { $showDiscussionHeading = 1; $contentString .= "
Constants
\n"; @@ -6321,6 +6409,19 @@ sub XMLdocumentationBlock { } } + my @embeddedClasses = (); + my $class_self = undef; + if ($self->lang eq "applescript" && $class eq "HeaderDoc::Function") { + if (!$self->{ASCONTENTSPROCESSED}) { + $class_self = $self->processAppleScriptFunctionContents(); + # $class_self->dbprint(); + my @classes = $class_self->classes(); + foreach my $obj (@classes) { + push(@embeddedClasses, $obj); + } + } + } + $langstring = $self->apiRefLanguage($sublang); # if ($sublang eq "cpp") { @@ -6793,7 +6894,14 @@ sub XMLdocumentationBlock { } $compositePageString .= "\n"; } - + if (@embeddedClasses) { + $contentString = $class_self->_getEmbeddedClassXMLDetailString(\@embeddedClasses); + if (length($contentString)) { + $compositePageString .= "\n"; + $compositePageString .= $contentString; + $compositePageString .= "\n"; + } + } if (@local_variables) { $compositePageString .= "\n"; foreach my $field (@local_variables) { @@ -9363,4 +9471,203 @@ sub prepareDiscussionForTemporary $self->{DISCUSSION_SET} = undef; } +# /*! +# @abstract +# Processes the cloned function/class object previously +# created by the {@link cloneAppleScriptFunctionContents} +# method. +# */ +sub processAppleScriptFunctionContents +{ + my $self = shift; + my $localDebug = 0; + + print STDERR "IN processAppleScriptFunctionContents\n" if ($localDebug); + $self->dbprint() if ($localDebug); + + # Grab the class object that contains the parsed contents of the function body. + my $class_self_ref = $self->{AS_CLASS_SELF}; + if (!$class_self_ref) { + die("Missing AS_CLASS_SELF for $self (".$self->name().")\n"); + } + my $class_self = ${$class_self_ref}; + bless($class_self, "HeaderDoc::HeaderElement"); + bless($class_self, $class_self->class()); + + # Copy the name and other info, now that it is known. + $class_self->{NAME} = $self->{NAME}; + $class_self->{RAWNAME} = $self->{RAWNAME}; + $class_self->{FORCENAME} = $self->{FORCENAME}; + $class_self->{NAMEREFS} = $self->{NAMEREFS}; + $class_self->{LANG} = $self->{LANG}; + $class_self->{OUTPUTFORMAT} = $self->{OUTPUTFORMAT}; + + # Determine the output mode. + my $xml_output = 0; + my $apiowner = $self->apiOwner(); + if ($apiowner->outputformat() eq "hdxml") { $xml_output = 1; } + + print STDERR "OF: ".$apiowner->outputformat()."\n" if ($localDebug); + + # Obtain the parse tree. + my $ptref = $class_self->{PARSETREE}; + bless($ptref, "HeaderDoc::ParseTree"); + my $parseTree = ${$ptref}; + + # Compute the name of the directory where the contents should be written (in HTML mode) + if (!$xml_output) { + my $className = $class_self->name(); + # for now, always shorten long names since some files may be moved to a Mac for browsing + if (1 || $isMacOS) {$className = &safeName(filename => $className);}; + $className = "parsedFunctionContents_$className"; + + my $classesDir = $self->apiOwner()->classesDir(); + if (! -e $classesDir) { + unless (mkdir ("$classesDir", 0777)) {die ("Can't create output folder $classesDir. \n$!");}; + } + + my $classRootDir = $self->apiOwner()->{OUTPUTDIR}; + $class_self->outputDir("$classRootDir$pathSeparator$className"); + $class_self->{PARSEDPSEUDOCLASSNAME} = $className; + } + + # Process the embedded tags and write out the contents. + $parseTree->processEmbeddedTags($xml_output, $class_self); + + # Write the output (in HTML mode) + if (!$xml_output) { + if ($class_self->classes()) { + print STDERR "CLASSES\n" if ($localDebug); + $class_self->writeHeaderElements(); + } else { + print STDERR "NO CLASSES\n" if ($localDebug); + } + } + $self->{ASCONTENTSPROCESSED} = 1; + + $parseTree->dbprint() if ($localDebug); + + return $class_self; +} + +# /*! +# @abstract +# Clones a function object for use as an API owner for any +# enclosing scripts. +# */ +sub cloneAppleScriptFunctionContents +{ + my $self = shift; + + my $localDebug = 0; + + if ($localDebug) { + print STDERR "Cloning $self for AppleScript function body parsing.\n"; + $self->dbprint(); + } + + my $class_self = HeaderDoc::CPPClass->new(); + $self->{AS_CLASS_SELF} = \$class_self; + + my $orig_ptref = $self->{PARSETREE}; + bless($orig_ptref, "HeaderDoc::ParseTree"); + my $parseTree = ${$orig_ptref}; + my $tree = $parseTree->clone(); + + # Don't copy the name here, because it hasn't been set yet, but copy + # the parse tree, because otherwise it gets stomped. + $class_self->{PARSETREE} = \$tree; + $class_self->{SUBLANG} = $self->{SUBLANG}; + $class_self->{APIOWNER} = $self->{APIOWNER}; + $class_self->{FILENAME} = $self->{FILENAME}; + $class_self->{FULLPATH} = $self->{FULLPATH}; + $class_self->{OUTPUTFORMAT} = $self->{OUTPUTFORMAT}; + + print STDERR "NAME: ".$class_self->name()."\n" if ($localDebug); + print STDERR "RAWNAME: ".$class_self->rawname()."\n" if ($localDebug); + print STDERR "TREE: $tree\n" if ($localDebug); + + $tree->apiOwner($class_self); +} + +# /*! +# @abstract +# Processes the cloned function/class object previously +# created by the {@link cloneAppleScriptFunctionContents} +# method. +# */ +sub processAppleScriptFunctionContents +{ + my $self = shift; + my $localDebug = 0; + + print STDERR "IN processAppleScriptFunctionContents\n" if ($localDebug); + $self->dbprint() if ($localDebug); + + # Grab the class object that contains the parsed contents of the function body. + my $class_self_ref = $self->{AS_CLASS_SELF}; + if (!$class_self_ref) { + die("Missing AS_CLASS_SELF for $self (".$self->name().")\n"); + } + my $class_self = ${$class_self_ref}; + bless($class_self, "HeaderDoc::HeaderElement"); + bless($class_self, $class_self->class()); + + # Copy the name and other info, now that it is known. + $class_self->{NAME} = $self->{NAME}; + $class_self->{RAWNAME} = $self->{RAWNAME}; + $class_self->{FORCENAME} = $self->{FORCENAME}; + $class_self->{NAMEREFS} = $self->{NAMEREFS}; + $class_self->{LANG} = $self->{LANG}; + $class_self->{OUTPUTFORMAT} = $self->{OUTPUTFORMAT}; + + # Determine the output mode. + my $xml_output = 0; + my $apiowner = $self->apiOwner(); + if ($apiowner->outputformat() eq "hdxml") { $xml_output = 1; } + + print STDERR "OF: ".$apiowner->outputformat()."\n" if ($localDebug); + + # Obtain the parse tree. + my $ptref = $class_self->{PARSETREE}; + bless($ptref, "HeaderDoc::ParseTree"); + my $parseTree = ${$ptref}; + + # Compute the name of the directory where the contents should be written (in HTML mode) + if (!$xml_output) { + my $className = $class_self->name(); + # for now, always shorten long names since some files may be moved to a Mac for browsing + if (1 || $isMacOS) {$className = &safeName(filename => $className);}; + $className = "parsedFunctionContents_$className"; + + my $classesDir = $self->apiOwner()->classesDir(); + if (! -e $classesDir) { + unless (mkdir ("$classesDir", 0777)) {die ("Can't create output folder $classesDir. \n$!");}; + } + + my $classRootDir = $self->apiOwner()->{OUTPUTDIR}; + $class_self->outputDir("$classRootDir$pathSeparator$className"); + $class_self->{PARSEDPSEUDOCLASSNAME} = $className; + } + + # Process the embedded tags and write out the contents. + $parseTree->processEmbeddedTags($xml_output, $class_self); + + # Write the output (in HTML mode) + if (!$xml_output) { + if ($class_self->classes()) { + print STDERR "CLASSES\n" if ($localDebug); + $class_self->writeHeaderElements(); + } else { + print STDERR "NO CLASSES\n" if ($localDebug); + } + } + $self->{ASCONTENTSPROCESSED} = 1; + + $parseTree->dbprint() if ($localDebug); + + return $class_self; +} + + 1; diff --git a/Modules/HeaderDoc/ParseTree.pm b/Modules/HeaderDoc/ParseTree.pm index 62d1ba4..4c5fd7b 100644 --- a/Modules/HeaderDoc/ParseTree.pm +++ b/Modules/HeaderDoc/ParseTree.pm @@ -2,7 +2,7 @@ # # Class name: ParseTree # Synopsis: Used by headerdoc2html to hold parse trees -# Last Updated: $Date: 2013/05/14 15:29:11 $ +# Last Updated: $Date: 2014/02/25 15:48:22 $ # # Copyright (c) 1999-2004 Apple Computer, Inc. All rights reserved. # @@ -177,7 +177,7 @@ use Carp qw(cluck); # In the git repository, contains the number of seconds since # January 1, 1970. # */ -$HeaderDoc::ParseTree::VERSION = '$Revision: 1368570551 $'; +$HeaderDoc::ParseTree::VERSION = '$Revision: 1393372102 $'; ################ General Constants ################################### my $debugging = 0; @@ -1002,12 +1002,15 @@ sub processEmbeddedTags my $localDebug = 0; # if ($apio->isAPIOwner()) { $localDebug = 1; } - print STDERR "PET: $apio\n" if ($localDebug); + print STDERR "IN PET\n" if ($localDebug); + print STDERR "API IS $apio\n" if ($localDebug); print STDERR $apio->name()."\n" if ($localDebug); print STDERR "APIOLIST IS $apiolist\n" if ($localDebug);; - # for my $tempapio (@{$apiolist}) { - # print STDERR "RETURNED APIOLIST INCLUDES $tempapio\n"; - # } + if ($localDebug && $apiolist) { + for my $tempapio (@{$apiolist}) { + print STDERR "RETURNED APIOLIST INCLUDES $tempapio (".($tempapio->rawname()).")\n"; + } + } ### Make the APIO owner list unique. ### @@ -1425,7 +1428,7 @@ sub APIOprocessEmbeddedTagsRec($$$$$$$$) print STDERR "NNTOKEN: $nntoken\n" if ($localDebug); if ((($lang ne "tcl" && ($ntoken eq "!" || ($enable_javadoc_comments && $ntoken eq "*" && $nntoken !~ /^\*/))) || ($lang eq "tcl" && ($ntoken eq "/*" && $nntoken eq "!" && $firstchild->next()->next()->next()))) && - !$self->hidden()) { + ($lang eq "applescript" || (!$self->hidden()))) { print STDERR "NODECHECK: $self\n" if ($localDebug); # HDCOMMENT $self->dbprint() if ($localDebug); @@ -1850,12 +1853,15 @@ print STDERR "LAST DECLARATION: $lastDeclaration\n" if ($localDebug); } if (!$HeaderDoc::dumb_as_dirt) { # Drop this comment from the output. - if ($xmlmode) { + if ($xmlmode || ($apio->lang() eq "applescript")) { # We were doing this for HTML when we needed to # be able to reparse the tree after copying # it to a cloned data type. This is no longer # needed, and the old method (above) is slightly # faster. + # + # However, we still have to use this approach + # for AppleScript, for that reason. $self->hidden(1); $skipchildren = 1; } else { $self->{TOKEN} = "";