#! /usr/bin/perl -w # # Class name: MinorAPIElement # Synopsis: Class for parameters and members of structs, etc. # # Last Updated: $Date: 2011/05/26 14:13:20 $ # # Copyright (c) 1999-2008 Apple Computer, Inc. All rights reserved. # # @APPLE_LICENSE_HEADER_START@ # # This file contains Original Code and/or Modifications of Original Code # as defined in and that are subject to the Apple Public Source License # Version 2.0 (the 'License'). You may not use this file except in # compliance with the License. Please obtain a copy of the License at # http://www.opensource.apple.com/apsl/ and read it before using this # file. # # The Original Code and all software distributed under the License are # distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER # EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, # INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. # Please see the License for the specific language governing rights and # limitations under the License. # # @APPLE_LICENSE_HEADER_END@ # ###################################################################### # /*! @header # @abstract # <code>MinorAPIElement</code> class package file. # @discussion # This file contains the <code>MinorAPIElement</code> class, a class for content # relating to an enumeration declaration. # # For details, see the class documentation below. # @indexgroup HeaderDoc API Objects # */ # /*! # @abstract # API object that describes an API element that is documented only # as part of another API element. # @discussion # The <code>MinorAPIElement</code> class stores information relating to a field # in a structure or type declaration, a constant in an enumeration, # or a parameter (parsed or tagged) to a function or callback typedef. # # This class is a subclass of # {@link //apple_ref/perl/cl/HeaderDoc::HeaderElement HeaderElement}. # The majority of related fields and functions can be found there. # # @var POSITION # The position of this element in the declaration. # See {@link position}. # @var TYPE # The type of minor API element. See # {@link //apple_ref/perl/instm/HeaderDoc::MinorAPIElement/type//() type}. # @var USERDICTARRAY # A bunch of key-value pairs in sorted order. # See {@link addToUserDictArray}. # @var USERDICT # A bunch of arbitrary key-value pairs in sorted order. # See {@link addKeyAndValueInUserDict}. # @var HIDDEN # Indicates that this should not be emitted in HTML. Used # in inherited bits. # @var AUTODECLARATION # A flag that is set to 1 for certain special declarations # (Perl instance variables or other variables created by the # <code>\@var</code> tag in class markup) to indicate that the discussion # functions should return a synthesized declaration rather # than anything from the parse tree. # @var TAGNAME # The label for an Objective-C method parameter. # */ package HeaderDoc::MinorAPIElement; use HeaderDoc::Utilities qw(findRelativePath safeName printArray printHash registerUID); use HeaderDoc::HeaderElement; use Carp qw(cluck); @ISA = qw( HeaderDoc::HeaderElement ); use strict; use vars qw($VERSION @ISA); # /*! # @abstract # The revision control revision number for this module. # @discussion # In the git repository, contains the number of seconds since # January 1, 1970. # */ $HeaderDoc::MinorAPIElement::VERSION = '$Revision: 1306444400 $'; # /*! # @abstract # Initializes an instance of a <code>MinorAPIElement</code> object. # @param self # The object to initialize. # */ sub _initialize { my($self) = shift; $self->SUPER::_initialize(); # $self->{POSITION} = undef; # $self->{TYPE} = undef; $self->{USERDICTARRAY} = (); # $self->{HIDDEN} = 0; $self->{CLASS} = "HeaderDoc::MinorAPIElement"; } # /*! # @abstract # Duplicates this <code>MinorAPIElement</code> object into another one. # @param self # The object to clone. # @param clone # The victim object. # */ sub clone { my $self = shift; my $clone = undef; if (@_) { $clone = shift; } else { $clone = HeaderDoc::MinorAPIElement->new("LANG" => $self->{LANG}, "SUBLANG" => $self->{SUBLANG}); } $self->SUPER::clone($clone); # now clone stuff specific to function $clone->{POSITION} = $self->{POSITION}; $clone->{TYPE} = $self->{TYPE}; $clone->{HIDDEN} = $self->{HIDDEN}; $clone->{USERDICTARRAY} = $self->{USERDICTARRAY}; return $clone; } # /*! # @abstract # Gets/sets the Objective-C label for a parameter. # @param self # This <code>MinorAPIElement</code> object. # @param TAGNAME # The new name. (Optional.) # */ sub tagname { my $self = shift; if (@_) { $self->{TAGNAME} = shift; } return $self->{TAGNAME}; } # /*! # @abstract # Gets/sets the position of this parameter. # @param self # This <code>MinorAPIElement</code> object. # @param POSITION # The new position. (Optional.) # @discussion # The first parameter has position 0, the second # has position 1, and so on. # */ sub position { my $self = shift; if (@_) { $self->{POSITION} = shift; } return $self->{POSITION}; } # /*! # @abstract # Gets/sets whether this parameter is hidden. # @param self # This <code>MinorAPIElement</code> object. # @param HIDDEN # The new value. (Optional.) # @discussion # Parsed parameters merged in from other places are # not emitted in the XML output. Set to 1 for # those parameters. Otherwise, set to 0 or leave # unset. # */ sub hidden { my $self = shift; if (@_) { $self->{HIDDEN} = shift; } return $self->{HIDDEN}; } # /*! # @abstract # Gets/sets what type of parameter this is. # @param self # This <code>MinorAPIElement</code> object. # @param TYPE # The new value. (Optional.) # @discussion # These values are one of: # # <ul> # <li>(empty string)</li> # <li><code>callback</code></li> # <li><code>funcPtr</code></li> # </ul> # */ sub type { my $self = shift; if (@_) { $self->{TYPE} = shift; } return $self->{TYPE}; } # /*! # @abstract # Gets/sets the user dictionary array. # @param self # This <code>MinorAPIElement</code> object. # @discussion # Used for miscellaneous data, such as the parameters # within a <code>typedef struct</code> of callbacks # stored as an array to preserve order. # */ sub userDictArray { my $self = shift; if (@_) { @{ $self->{USERDICTARRAY} } = @_; } ($self->{USERDICTARRAY}) ? return @{ $self->{USERDICTARRAY} } : return (); } # /*! # @abstract # Adds values to the user dictionary array (and returns it). # @param self # This <code>MinorAPIElement</code> object. # @param ... # The objects to add. # @discussion # Used for miscellaneous data, such as the parameters # within a <code>typedef struct</code> of callbacks # stored as an array to preserve order. # */ sub addToUserDictArray { my $self = shift; if (@_) { foreach my $item (@_) { push (@{ $self->{USERDICTARRAY} }, $item); } } return @{ $self->{USERDICTARRAY} }; } # /*! # @abstract # Adds key-value pairs to the user dictionary # (and returns it). # @param self # This <code>MinorAPIElement</code> object. # @param ... # The objects to add. # @discussion # Used for miscellaneous data. # */ sub addKeyAndValueInUserDict { my $self = shift; if (@_) { my $key = shift; my $value = shift; $self->{USERDICT}{$key} = $value; } return %{ $self->{USERDICT} }; } # /*! # @abstract # Prints this object for debugging purposes. # @param self # This object. # */ sub printObject { my $self = shift; my $dec = $self->declaration(); $self->SUPER::printObject(); print STDERR "position: $self->{POSITION}\n"; print STDERR "type: $self->{TYPE}\n"; } # /*! # @param value # @abstract # Sets or gets a state flag. # @discussion # The APPLEREFISDOC state flag controls whether to use a # language-specific or doc-specific apple_ref marker for a # doc block. # # This version overrides the # {@link //apple_ref/perl/instm/HeaderDoc::HeaderElement/appleRefIsDoc//() appleRefIsDoc} # method in # {@link //apple_ref/perl/cl/HeaderDoc::HeaderElement HeaderDoc::HeaderElement} # because of the complexity of working with minor API # elements that live in normal (non-API-owner) objects. # */ sub appleRefIsDoc { my $self = shift; if (@_) { my $value = shift; $self->{APPLEREFISDOC} = $value; } # print STDERR "ARID: ".$self->{APPLEREFISDOC}." for $self\n"; if ($self->{APPLEREFISDOC}) { return $self->{APPLEREFISDOC}; } elsif ($self->apiOwner()) { my $apio = $self->apiOwner(); bless($apio, "HeaderDoc::HeaderElement"); bless($apio, $apio->class()); my $apioval = $apio->appleRefIsDoc(); # print STDERR "APIOVAL: $apioval for $apio (".$apio->name().")\n"; if ($apioval) { return $apioval; } } return $self->{APPLEREFISDOC}; } # /*! # @abstract # Sets the group. # @discussion # This overrides the declaration in HeaderElement.pm because # we want the groups for local variables to be separate and # distinct from normal function/data type/variable groups unless # the owning object really is an APIOwner subclass. # */ sub group { my $self = shift; if ($self->apiOwner()->isAPIOwner()) { return $self->SUPER::group(@_); } if (@_) { $self->{GROUP} = shift; } return $self->{GROUP}; } # /*! # @abstract # Gets/sets the legacy text declaration. # @param self # This <code>MinorAPIElement</code> object. # @discussion # For special declarations (Perl instance variables, # function-local variables, and so on), # returns a synthesized declaration from # {@link //apple_ref/perl/data/HeaderDoc::MinorAPIElement/AUTODECLARATION AUTODECLARATION}. # Otherwise, hands off the request to the superclass, # {@link //apple_ref/perl/cl/HeaderDoc::HeaderElement HeaderElement}. # */ sub declaration { my $self = shift; if ($self->{AUTODECLARATION}) { return $self->{AUTODECLARATION}; } return $self->SUPER::declaration(); } # /*! # @abstract # Gets the HTML declaration. # @param self # This <code>MinorAPIElement</code> object. # @discussion # For special declarations (Perl instance variables, # function-local variables, and so on), # returns a synthesized declaration from # {@link //apple_ref/perl/data/HeaderDoc::MinorAPIElement/AUTODECLARATION AUTODECLARATION}. # Otherwise, hands off the request to the superclass, # {@link //apple_ref/perl/cl/HeaderDoc::HeaderElement HeaderElement}. # */ sub declarationInHTML { my $self = shift; if ($self->{AUTODECLARATION}) { return $self->{AUTODECLARATION}; } return $self->SUPER::declarationInHTML(); } # /*! # @abstract # Gets/sets the # {@link //apple_ref/perl/data/HeaderDoc::MinorAPIElement/AUTODECLARATION AUTODECLARATION} # value. # @param self # This <code>MinorAPIElement</code> object. # @param AUTODECLARATION # The new value to set. # @discussion # For special declarations (Perl instance variables, # function-local variables, and so on), declaration functions # return a synthesized declaration based on the # {@link //apple_ref/doc/functionparam/HeaderDoc::MinorAPIElement/autodeclaration/AUTODECLARATION AUTODECLARATION} # parameter. This function supports that. # */ sub autodeclaration { my $self = shift; if (@_) { if ($self->lang() eq "perl") { $self->{AUTODECLARATION} = "\$self->{".$self->name()."}"; } else { $self->{AUTODECLARATION} = $self->name(); } } return $self->{AUTODECLARATION}; } # /*! # @abstract # Returns a custom API reference for function # parameters, struct fields, and so on. # @discussion # Overrides the function in # {@link //apple_ref/perl/cl/HeaderDoc::HeaderElement HeaderElement} # because these minor API elements need lots of special # treatment. In particular, this function only # overrides the behavior if the main function does not # return anything. This is necessary because some other # data types use the <code>MinorAPIElement</code> class # in nonstandard ways. # */ sub apiuid { my $self = shift; my $args = 0; my $type = "AUTO"; my $paramSignature_or_alt_define_name = ""; if (@_) { $args = 1; $type = shift; if (@_) { $paramSignature_or_alt_define_name = shift; } } my $ret = ""; if ($args) { $ret = $self->SUPER::apiuid($type, $paramSignature_or_alt_define_name); } else { $ret = $self->SUPER::apiuid(); } # print STDERR "MINORAPIELEMENT NAME: ".$self->name()." UID: $ret\n"; my $apiUIDPrefix = HeaderDoc::APIOwner->apiUIDPrefix(); if ($ret eq "") { my $fieldtype = ""; my $apio = $self->apiOwner(); my $apioclass = ref($apio) || $apio; if (!$apio) { # We're disposing of the node. Return the last known value. return $self->{APIUID}; } my $include_class = 1; if ($apioclass eq "HeaderDoc::Enum") { $fieldtype = "enumconstant"; } elsif ($apioclass eq "HeaderDoc::Function") { $fieldtype = "functionparam"; if ($self->autodeclaration()) { $fieldtype = "functionvar"; } } elsif ($apioclass eq "HeaderDoc::Method") { $fieldtype = "methodparam"; if ($self->autodeclaration()) { $fieldtype = "methodvar"; } } elsif ($apioclass eq "HeaderDoc::PDefine") { $fieldtype = "defineparam"; if ($self->autodeclaration()) { $fieldtype = "definevar"; } $include_class = 0; } elsif ($apioclass eq "HeaderDoc::Struct") { $fieldtype = "structfield"; } elsif ($apioclass eq "HeaderDoc::Typedef") { $fieldtype = "typedeffield"; } elsif ($apioclass eq "HeaderDoc::Var") { $fieldtype = "typedeffield"; } if ($fieldtype) { my $apiOwnerOwner = $apio->apiOwner(); my $apiOwnerOwnerClass = ref($apiOwnerOwner) || $apiOwnerOwner; my $uid = ""; if ((!$include_class) || ($apiOwnerOwnerClass eq "HeaderDoc::Header") || (!$apiOwnerOwner)) { $uid = $self->genRefSub("doc", $fieldtype, $self->apiuidname, $apio->apiuidname()); } else { $uid = $self->genRefSub("doc", $fieldtype, $self->apiuidname, $apio->apiuidname(), undef, $apiOwnerOwner->apiuidname); } # print STDERR $self->name().": //$apiUIDPrefix/doc/$fieldtype/".$apio->apiuidname()."/".$self->name()." VERSUS $uid\n"; # return "//$apiUIDPrefix/doc/$fieldtype/".$apio->apiuidname()."/".$self->name(); $self->{APIUID} = $uid; registerUID($uid, $self->rawname(), $self); return $uid; } } return $ret; } 1;