1 /******************************************************************************

     2  *

     3  * 

     4  *

     5  * Copyright (C) 1997-2008 by Dimitri van Heesch.

     6  *

     7  * Permission to use, copy, modify, and distribute this software and its

     8  * documentation under the terms of the GNU General Public License is hereby 

     9  * granted. No representations are made about the suitability of this software 

    10  * for any purpose. It is provided "as is" without express or implied warranty.

    11  * See the GNU General Public License for more details.

    12  *

    13  * Documents produced by Doxygen are derivative works derived from the

    14  * input used in their production; they are not affected by this license.

    15  *

    16  */

    17 

    18 #include <stdio.h>

    19 #include <qfile.h>

    20 #include <qregexp.h>

    21 #include "classdef.h"

    22 #include "classlist.h"

    23 #include "entry.h"

    24 #include "doxygen.h"

    25 #include "membername.h"

    26 #include "message.h"

    27 #include "config.h"

    28 #include "util.h"

    29 #include "diagram.h"

    30 #include "language.h"

    31 #include "htmlhelp.h"

    32 #include "example.h"

    33 #include "outputlist.h"

    34 #include "dot.h"

    35 #include "defargs.h"

    36 #include "debug.h"

    37 #include "docparser.h"

    38 #include "searchindex.h"

    39 #include "vhdldocgen.h"

    40 #include "layout.h"

    41 

    42 //-----------------------------------------------------------------------------

    43 

    44 //static inline MemberList *createNewMemberList(MemberList::ListType lt)

    45 //{

    46 //  MemberList *result = new MemberList(lt);

    47 //  return result;

    48 //}

    49 

    50 class ClassDefImpl

    51 {

    52   public:

    53     ClassDefImpl();

    54    ~ClassDefImpl();

    55     void init(const char *defFileName, const char *name,

    56               const QCString &ctStr, const char *fName);

    57 

    58     /*! file name that forms the base for the output file containing the

    59      *  class documentation. For compatibility with Qt (e.g. links via tag 

    60      *  files) this name cannot be derived from the class name directly.

    61      */

    62     QCString fileName;                   

    63 

    64     /*! Include information about the header file should be included

    65      *  in the documentation. 0 by default, set by setIncludeFile().

    66      */

    67     IncludeInfo *incInfo;                

    68 

    69     /*! List of base class (or super-classes) from which this class derives

    70      *  directly. 

    71      */

    72     BaseClassList *inherits;

    73 

    74     /*! List of sub-classes that directly derive from this class 

    75      */

    76     BaseClassList *inheritedBy;

    77 

    78     /*! Namespace this class is part of 

    79      *  (this is the inner most namespace in case of nested namespaces)

    80      */

    81     NamespaceDef  *nspace;              

    82 

    83     /*! File this class is defined in */

    84     FileDef *fileDef;

    85 

    86     /*! List of all members (including inherited members) */

    87     MemberNameInfoSDict *allMemberNameInfoSDict;

    88 

    89     /*! Template arguments of this class */

    90     ArgumentList *tempArgs;

    91 

    92     /*! Type constraints for template parameters */

    93     ArgumentList *typeConstraints;

    94 

    95     /*! Files that were used for generating the class documentation. */

    96     QStrList files;

    97 

    98     /*! Examples that use this class */

    99     ExampleSDict *exampleSDict;

   100 

   101     /*! Holds the kind of "class" this is. */

   102     ClassDef::CompoundType compType;

   103 

   104     /*! The protection level in which this class was found. 

   105      *  Typically Public, but for nested classes this can also be Protected

   106      *  or Private.

   107      */ 

   108     Protection prot;

   109 

   110     /*! The inner classes contained in this class. Will be 0 if there are

   111      *  no inner classes.

   112      */

   113     ClassSDict *innerClasses;

   114 

   115     /* classes for the collaboration diagram */

   116     UsesClassDict *usesImplClassDict;

   117     UsesClassDict *usedByImplClassDict;

   118     UsesClassDict *usesIntfClassDict;

   119 

   120     /*! Template instances that exists of this class, the key in the

   121      *  dictionary is the template argument list.

   122      */ 

   123     QDict<ClassDef> *templateInstances;

   124 

   125     /*! Template instances that exists of this class, as defined by variables.

   126      *  We do NOT want to document these individually. The key in the

   127      *  dictionary is the template argument list.

   128      */ 

   129     QDict<ClassDef> *variableInstances;

   130 

   131     QDict<int> *templBaseClassNames;

   132 

   133     /*! The class this class is an instance of. */

   134     ClassDef *templateMaster;

   135 

   136     /*! local class name which could be a typedef'ed alias name. */

   137     QCString className;

   138 

   139     /*! If this class is a Objective-C category, then this points to the

   140      *  class which is extended.

   141      */

   142     ClassDef *categoryOf;

   143 

   144     QList<MemberList> memberLists;

   145 

   146     /* user defined member groups */

   147     MemberGroupSDict *memberGroupSDict;

   148 

   149     /*! Is this an abstact class? */

   150     bool isAbstract;

   151 

   152     /*! Is the class part of an unnamed namespace? */

   153     bool isStatic;

   154 

   155     /*! Is the class part implemented in Objective C? */

   156     bool isObjC;

   157 

   158     /*! TRUE if classes members are merged with those of the base classes. */

   159     bool membersMerged;

   160 

   161     /*! TRUE if the class is defined in a source file rather than a header file. */

   162     bool isLocal;

   163 

   164     bool isTemplArg;

   165 

   166     /*! Does this class group its user-grouped members

   167      *  as a sub-section of the normal (public/protected/..) 

   168      *  groups?

   169      */

   170     bool subGrouping; 

   171 

   172     bool usedOnly;

   173 };

   174 

   175 void ClassDefImpl::init(const char *defFileName, const char *name,

   176                         const QCString &ctStr, const char *fName)

   177 {

   178   if (fName)

   179   {

   180     fileName=stripExtension(fName);

   181   }

   182   else

   183   {

   184     fileName=ctStr+name;

   185   }

   186   exampleSDict = 0;

   187   inherits    = 0;

   188   inheritedBy = 0;

   189   allMemberNameInfoSDict = 0;

   190   incInfo=0;

   191   tempArgs=0;

   192   typeConstraints=0;

   193   prot=Public;

   194   nspace=0;

   195   fileDef=0;

   196   usesImplClassDict=0;

   197   usedByImplClassDict=0;

   198   usesIntfClassDict=0;

   199   memberGroupSDict = 0;

   200   innerClasses = 0;

   201   subGrouping=Config_getBool("SUBGROUPING");

   202   templateInstances = 0;

   203   variableInstances = 0;

   204   templateMaster =0;

   205   templBaseClassNames = 0;

   206   isAbstract = FALSE;

   207   isStatic = FALSE;

   208   isTemplArg = FALSE;

   209   membersMerged = FALSE;

   210   categoryOf = 0;

   211   usedOnly = FALSE;

   212   //QCString ns;

   213   //extractNamespaceName(name,className,ns);

   214   //printf("m_name=%s m_className=%s ns=%s\n",m_name.data(),m_className.data(),ns.data());

   215 

   216   if (((QCString)defFileName).right(5)!=".java" && 

   217       guessSection(defFileName)==Entry::SOURCE_SEC)

   218   {

   219     isLocal=TRUE;

   220   }

   221   else

   222   {

   223     isLocal=FALSE;

   224   }

   225 }

   226 

   227 ClassDefImpl::ClassDefImpl()

   228 {

   229 }

   230 

   231 ClassDefImpl::~ClassDefImpl()

   232 {

   233   delete inherits;

   234   delete inheritedBy;

   235   delete allMemberNameInfoSDict;

   236   delete exampleSDict;

   237   delete usesImplClassDict;

   238   delete usedByImplClassDict;

   239   delete usesIntfClassDict;

   240   delete incInfo;

   241   delete memberGroupSDict;

   242   delete innerClasses;

   243   delete templateInstances;

   244   delete variableInstances;

   245   delete templBaseClassNames;

   246   delete tempArgs;

   247   delete typeConstraints;

   248 }

   249 

   250 // constructs a new class definition

   251 ClassDef::ClassDef(

   252     const char *defFileName,int defLine,

   253     const char *nm,CompoundType ct,

   254     const char *lref,const char *fName,

   255     bool isSymbol) 

   256  : Definition(defFileName,defLine,removeRedundantWhiteSpace(nm),0,0,isSymbol) 

   257 {

   258   visited=FALSE;

   259   setReference(lref);

   260   m_impl = new ClassDefImpl;

   261   m_impl->compType = ct;

   262   m_impl->isObjC   = FALSE;

   263   m_impl->init(defFileName,name(),compoundTypeString(),fName);

   264 

   265 }

   266 

   267 // destroy the class definition

   268 ClassDef::~ClassDef()

   269 {

   270   delete m_impl;

   271 }

   272 

   273 QCString ClassDef::getMemberListFileName() const

   274 {

   275   return convertNameToFile(compoundTypeString()+name()+"-members");

   276 }

   277 

   278 QCString ClassDef::displayName() const

   279 {

   280   static bool optimizeOutputForJava = Config_getBool("OPTIMIZE_OUTPUT_JAVA");

   281   static bool vhdlOpt = Config_getBool("OPTIMIZE_OUTPUT_VHDL");

   282   QCString n;

   283   if (vhdlOpt)

   284   {

   285     n = VhdlDocGen::getClassName(this);

   286   }

   287   else 

   288   {

   289     n=qualifiedNameWithTemplateParameters();

   290   }

   291   if (optimizeOutputForJava)

   292   {

   293     n=substitute(n,"::",".");

   294   }

   295   if (m_impl->compType==ClassDef::Protocol && n.right(2)=="-p")

   296   {

   297     n="<"+n.left(n.length()-2)+">";

   298   }

   299   return n;

   300 }

   301 

   302 // inserts a base class in the inheritance list

   303 void ClassDef::insertBaseClass(ClassDef *cd,const char *n,Protection p,

   304                                Specifier s,const char *t)

   305 {

   306   //printf("*** insert base class %s into %s\n",cd->name().data(),name().data());

   307   //inherits->inSort(new BaseClassDef(cd,p,s,t));

   308   if (m_impl->inherits==0)

   309   {

   310     m_impl->inherits = new BaseClassList;

   311     m_impl->inherits->setAutoDelete(TRUE);

   312   }

   313   m_impl->inherits->append(new BaseClassDef(cd,n,p,s,t));

   314 }

   315 

   316 // inserts a sub class in the inherited list

   317 void ClassDef::insertSubClass(ClassDef *cd,Protection p,

   318                                 Specifier s,const char *t)

   319 {

   320   //printf("*** insert sub class %s into %s\n",cd->name().data(),name().data());

   321   if (m_impl->inheritedBy==0)

   322   {

   323     m_impl->inheritedBy   = new BaseClassList;

   324     m_impl->inheritedBy->setAutoDelete(TRUE);

   325   }

   326   m_impl->inheritedBy->inSort(new BaseClassDef(cd,0,p,s,t));

   327 }

   328 

   329 void ClassDef::addMembersToMemberGroup()

   330 {

   331   QListIterator<MemberList> mli(m_impl->memberLists);

   332   MemberList *ml;

   333   for (mli.toFirst();(ml=mli.current());++mli)

   334   {

   335     if ((ml->listType()&MemberList::detailedLists)==0)

   336     {

   337       ::addMembersToMemberGroup(ml,&m_impl->memberGroupSDict,this);

   338     }

   339   }

   340 

   341   // add members inside sections to their groups

   342   if (m_impl->memberGroupSDict)

   343   {

   344     MemberGroupSDict::Iterator mgli(*m_impl->memberGroupSDict);

   345     MemberGroup *mg;

   346     for (;(mg=mgli.current());++mgli)

   347     {

   348       if (mg->allMembersInSameSection() && m_impl->subGrouping) 

   349       {

   350         //printf("addToDeclarationSection(%s)\n",mg->header().data());

   351         mg->addToDeclarationSection();

   352       }

   353     }

   354   }

   355 }

   356 

   357 // adds new member definition to the class

   358 void ClassDef::internalInsertMember(MemberDef *md,

   359                                     Protection prot,

   360                                     bool addToAllList

   361                                    )

   362 {

   363   //printf("insertInternalMember(%s) isHidden()=%d\n",md->name().data(),md->isHidden());

   364   if (md->isHidden()) return;

   365 

   366   if (!isReference())

   367   {

   368     static bool extractPrivate = Config_getBool("EXTRACT_PRIVATE");

   369 

   370     /********************************************/

   371     /* insert member in the declaration section */

   372     /********************************************/

   373     if (md->isRelated() && (extractPrivate || prot!=Private))

   374     {

   375       addMemberToList(MemberList::related,md,true);

   376     }

   377     else if (md->isFriend())

   378     {

   379       addMemberToList(MemberList::friends,md,true);

   380     }

   381     else

   382     {

   383       switch (md->memberType())

   384       {

   385         case MemberDef::Signal: // Qt specific

   386           addMemberToList(MemberList::signals,md,true);

   387           break;

   388         case MemberDef::DCOP:   // KDE2 specific

   389           addMemberToList(MemberList::dcopMethods,md,true);

   390           break;

   391         case MemberDef::Property:

   392           addMemberToList(MemberList::properties,md,true);

   393           break;

   394         case MemberDef::Event:

   395           addMemberToList(MemberList::events,md,true);

   396           break;

   397         case MemberDef::Slot:   // Qt specific

   398           switch (prot)

   399           {

   400             case Protected: 

   401             case Package: // slots in packages are not possible!

   402               addMemberToList(MemberList::proSlots,md,true);

   403               break;

   404             case Public:    

   405               addMemberToList(MemberList::pubSlots,md,true);

   406               break;

   407             case Private:   

   408               addMemberToList(MemberList::priSlots,md,true);

   409               break;

   410           }

   411           break;

   412         default: // any of the other members

   413           if (md->isStatic())

   414           {

   415             if (md->isVariable())

   416             {

   417               switch (prot)

   418               {

   419                 case Protected: 

   420                   addMemberToList(MemberList::proStaticAttribs,md,true);

   421                   break;

   422                 case Package: 

   423                   addMemberToList(MemberList::pacStaticAttribs,md,true);

   424                   break;

   425                 case Public:    

   426                   addMemberToList(MemberList::pubStaticAttribs,md,true);

   427                   break;

   428                 case Private:   

   429                   addMemberToList(MemberList::priStaticAttribs,md,true);

   430                   break;

   431               }

   432             }

   433             else // function

   434             {

   435               switch (prot)

   436               {

   437                 case Protected: 

   438                   addMemberToList(MemberList::proStaticMethods,md,true);

   439                   break;

   440                 case Package: 

   441                   addMemberToList(MemberList::pacStaticMethods,md,true);

   442                   break;

   443                 case Public:    

   444                   addMemberToList(MemberList::pubStaticMethods,md,true);

   445                   break;

   446                 case Private:   

   447                   addMemberToList(MemberList::priStaticMethods,md,true);

   448                   break;

   449               }

   450             }

   451           }

   452           else // not static

   453           {

   454             if (md->isVariable())

   455             {

   456               switch (prot)

   457               {

   458                 case Protected: 

   459                   addMemberToList(MemberList::proAttribs,md,true);

   460                   break;

   461                 case Package:

   462                   addMemberToList(MemberList::pacAttribs,md,true);

   463                   break;

   464                 case Public:    

   465                   addMemberToList(MemberList::pubAttribs,md,true);

   466                   break;

   467                 case Private:   

   468                   addMemberToList(MemberList::priAttribs,md,true);

   469                   break;

   470               }

   471             }

   472             else if (md->isTypedef() || md->isEnumerate() || md->isEnumValue())

   473             {

   474               switch (prot)

   475               {

   476                 case Protected: 

   477                   addMemberToList(MemberList::proTypes,md,true);

   478                   break;

   479                 case Package: 

   480                   addMemberToList(MemberList::pacTypes,md,true);

   481                   break;

   482                 case Public:    

   483                   addMemberToList(MemberList::pubTypes,md,true);

   484                   break;

   485                 case Private:   

   486                   addMemberToList(MemberList::priTypes,md,true);

   487                   break;

   488               }

   489             }

   490             else // member function

   491             {

   492               switch (prot)

   493               {

   494                 case Protected: 

   495                   addMemberToList(MemberList::proMethods,md,true);

   496                   break;

   497                 case Package: 

   498                   addMemberToList(MemberList::pacMethods,md,true);

   499                   break;

   500                 case Public:    

   501                   addMemberToList(MemberList::pubMethods,md,true);

   502                   break;

   503                 case Private:   

   504                   addMemberToList(MemberList::priMethods,md,true);

   505                   break;

   506               }

   507             }

   508           }

   509           break; 

   510       }

   511     }

   512 

   513     /*******************************************************/

   514     /* insert member in the detailed documentation section */

   515     /*******************************************************/

   516     if ((md->isRelated() && (extractPrivate || prot!=Private)) || md->isFriend())

   517     {

   518       addMemberToList(MemberList::relatedMembers,md,false);

   519     }

   520     else

   521     {

   522       switch (md->memberType())

   523       {

   524         case MemberDef::Property:

   525           addMemberToList(MemberList::propertyMembers,md,false);

   526           break;

   527         case MemberDef::Event:

   528           addMemberToList(MemberList::eventMembers,md,false);

   529           break;

   530         case MemberDef::Signal: // fall through

   531         case MemberDef::DCOP:

   532           addMemberToList(MemberList::functionMembers,md,false);

   533           break;

   534         case MemberDef::Slot:

   535           switch (prot)

   536           {

   537             case Protected: 

   538             case Package: 

   539             case Public:    

   540               addMemberToList(MemberList::functionMembers,md,false);

   541               break;

   542             case Private:   

   543               if (extractPrivate)

   544               {

   545                 addMemberToList(MemberList::functionMembers,md,false);

   546               }

   547               break;

   548           }

   549           break;

   550         default: // any of the other members

   551           if (prot!=Private || extractPrivate)

   552           {

   553             switch (md->memberType())

   554             {

   555               case MemberDef::Typedef:

   556                 addMemberToList(MemberList::typedefMembers,md,false);

   557                 break;

   558               case MemberDef::Enumeration:

   559                 addMemberToList(MemberList::enumMembers,md,false);

   560                 break;

   561               case MemberDef::EnumValue:

   562                 addMemberToList(MemberList::enumValMembers,md,false);

   563                 break;

   564               case MemberDef::Function:

   565                 if (md->isConstructor() || md->isDestructor())

   566                 {

   567                   MemberList *ml = createMemberList(MemberList::constructors);

   568                   ml->append(md);

   569                 }

   570                 else

   571                 {

   572                   addMemberToList(MemberList::functionMembers,md,false);

   573                 }

   574                 break;

   575               case MemberDef::Variable:

   576                 addMemberToList(MemberList::variableMembers,md,false);

   577                 break;

   578               default:

   579                 err("Unexpected member type %d found!\n",md->memberType());

   580             }

   581           }

   582           break; 

   583       }

   584     }

   585 

   586     /*************************************************/

   587     /* insert member in the appropriate member group */

   588     /*************************************************/

   589     // Note: this must be done AFTER inserting the member in the 

   590     // regular groups

   591     //addMemberToGroup(md,groupId);

   592     

   593   }

   594 

   595   if (md->virtualness()==Pure)

   596   {

   597     m_impl->isAbstract=TRUE;

   598   }

   599 

   600   //::addClassMemberNameToIndex(md);

   601   if (addToAllList && 

   602       !(Config_getBool("HIDE_FRIEND_COMPOUNDS") &&

   603         md->isFriend() &&

   604         (QCString(md->typeString())=="friend class" || 

   605          QCString(md->typeString())=="friend struct" ||

   606          QCString(md->typeString())=="friend union")))

   607   {

   608     //printf("=======> adding member %s to class %s\n",md->name().data(),name().data());

   609     MemberInfo *mi = new MemberInfo((MemberDef *)md,

   610                                      prot,md->virtualness(),FALSE);

   611     MemberNameInfo *mni=0;

   612     if (m_impl->allMemberNameInfoSDict==0)

   613     {

   614       m_impl->allMemberNameInfoSDict = new MemberNameInfoSDict(17);

   615       m_impl->allMemberNameInfoSDict->setAutoDelete(TRUE);

   616     }

   617     if ((mni=m_impl->allMemberNameInfoSDict->find(md->name())))

   618     {

   619       mni->append(mi);

   620     }

   621     else

   622     {

   623       mni = new MemberNameInfo(md->name());

   624       mni->append(mi);

   625       m_impl->allMemberNameInfoSDict->append(mni->memberName(),mni);

   626     }

   627   }

   628 }

   629 

   630 void ClassDef::insertMember(MemberDef *md)

   631 {

   632   internalInsertMember(md,md->protection(),TRUE);

   633 }

   634 

   635 // compute the anchors for all members

   636 void ClassDef::computeAnchors()

   637 {

   638   ClassDef *context = Config_getBool("INLINE_INHERITED_MEMB") ? this : 0;

   639   const char *letters = "abcdefghijklmnopqrstuvwxyz0123456789";

   640   QListIterator<MemberList> mli(m_impl->memberLists);

   641   MemberList *ml;

   642   int index = 0;

   643   for (mli.toFirst();(ml=mli.current());++mli)

   644   {

   645     if ((ml->listType()&MemberList::detailedLists)==0)

   646     {

   647       setAnchors(context,letters[index++],ml);

   648     }

   649   }

   650 

   651   if (m_impl->memberGroupSDict)

   652   {

   653     MemberGroupSDict::Iterator mgli(*m_impl->memberGroupSDict);

   654     MemberGroup *mg;

   655     for (;(mg=mgli.current());++mgli)

   656     {

   657       mg->setAnchors(context);

   658     }

   659   }

   660 }

   661 

   662 void ClassDef::distributeMemberGroupDocumentation()

   663 {

   664   if (m_impl->memberGroupSDict)

   665   {

   666     MemberGroupSDict::Iterator mgli(*m_impl->memberGroupSDict);

   667     MemberGroup *mg;

   668     for (;(mg=mgli.current());++mgli)

   669     {

   670       mg->distributeMemberGroupDocumentation();

   671     }

   672   }

   673 }

   674 

   675 void ClassDef::findSectionsInDocumentation()

   676 {

   677   docFindSections(documentation(),this,0,docFile());

   678   if (m_impl->memberGroupSDict)

   679   {

   680     MemberGroupSDict::Iterator mgli(*m_impl->memberGroupSDict);

   681     MemberGroup *mg;

   682     for (;(mg=mgli.current());++mgli)

   683     {

   684       mg->findSectionsInDocumentation();

   685     }

   686   }

   687   QListIterator<MemberList> mli(m_impl->memberLists);

   688   MemberList *ml;

   689   for (mli.toFirst();(ml=mli.current());++mli)

   690   {

   691     if ((ml->listType()&MemberList::detailedLists)==0)

   692     {

   693       ml->findSectionsInDocumentation();

   694     }

   695   }

   696 }

   697 

   698 

   699 // add a file name to the used files set

   700 void ClassDef::insertUsedFile(const char *f)

   701 {

   702   if (m_impl->files.find(f)==-1) m_impl->files.append(f);

   703   if (m_impl->templateInstances)

   704   {

   705     QDictIterator<ClassDef> qdi(*m_impl->templateInstances);

   706     ClassDef *cd;

   707     for (qdi.toFirst();(cd=qdi.current());++qdi)

   708     {

   709       cd->insertUsedFile(f);

   710     }

   711   }

   712 }

   713 

   714 static void writeInheritanceSpecifier(OutputList &ol,BaseClassDef *bcd)

   715 {

   716   if (bcd->prot!=Public || bcd->virt!=Normal)

   717   {

   718     ol.startTypewriter();

   719     ol.docify(" [");

   720     QStrList sl;

   721     if (bcd->prot==Protected)    sl.append("protected");

   722     else if (bcd->prot==Private) sl.append("private");

   723     if (bcd->virt==Virtual)      sl.append("virtual");

   724     const char *s=sl.first();

   725     while (s)

   726     {

   727       ol.docify(s);

   728       s=sl.next();

   729       if (s) ol.docify(", ");

   730     }

   731     ol.docify("]");

   732     ol.endTypewriter();

   733   }

   734 }

   735 

   736 void ClassDef::setIncludeFile(FileDef *fd,

   737              const char *includeName,bool local, bool force)

   738 {

   739   //printf("ClassDef::setIncludeFile(%p,%s,%d,%d)\n",fd,includeName,local,force);

   740   if (!m_impl->incInfo) m_impl->incInfo=new IncludeInfo;

   741   if ((includeName && m_impl->incInfo->includeName.isEmpty()) ||

   742       (fd!=0 && m_impl->incInfo->fileDef==0)

   743      )

   744   {

   745     //printf("Setting file info\n");

   746     m_impl->incInfo->fileDef     = fd;

   747     m_impl->incInfo->includeName = includeName;

   748     m_impl->incInfo->local       = local;

   749   }

   750   if (force && includeName) m_impl->incInfo->includeName = includeName;

   751 }

   752 

   753 // TODO: fix this: a nested template class can have multiple outer templates

   754 //ArgumentList *ClassDef::outerTemplateArguments() const

   755 //{

   756 //  int ti;

   757 //  ClassDef *pcd=0;

   758 //  int pi=0;

   759 //  if (m_impl->tempArgs) return m_impl->tempArgs;

   760 //  // find the outer most class scope

   761 //  while ((ti=name().find("::",pi))!=-1 && 

   762 //      (pcd=getClass(name().left(ti)))==0

   763 //        ) pi=ti+2;

   764 //  if (pcd)

   765 //  {

   766 //    return pcd->templateArguments();

   767 //  }

   768 //  return 0;

   769 //}

   770 

   771 static void searchTemplateSpecs(/*in*/  Definition *d,

   772                                 /*out*/ QList<ArgumentList> &result,

   773                                 /*out*/ QCString &name)

   774 {

   775   if (d->definitionType()==Definition::TypeClass)

   776   {

   777     if (d->getOuterScope())

   778     {

   779       searchTemplateSpecs(d->getOuterScope(),result,name);

   780     }

   781     ClassDef *cd=(ClassDef *)d;

   782     if (!name.isEmpty()) name+="::";

   783     name+=d->localName();

   784     bool isSpecialization = d->localName().find('<')!=-1;

   785     if (cd->templateArguments()) 

   786     {

   787       result.append(cd->templateArguments());

   788       if (!isSpecialization)

   789       {

   790         name+=tempArgListToString(cd->templateArguments());

   791       }

   792     }

   793   }

   794   else

   795   {

   796     name+=d->qualifiedName();

   797   }

   798 }

   799 

   800 static void writeTemplateSpec(OutputList &ol,Definition *d,

   801             const QCString &type)

   802 {

   803   QList<ArgumentList> specs;

   804   QCString name;

   805   searchTemplateSpecs(d,specs,name);

   806   if (specs.count()>0) // class has template scope specifiers

   807   {

   808     ol.startSubsubsection(); 

   809     QListIterator<ArgumentList> spi(specs);

   810     ArgumentList *al;

   811     for (spi.toFirst();(al=spi.current());++spi)

   812     {

   813       ol.docify("template<");

   814       Argument *a=al->first();

   815       while (a)

   816       {

   817         ol.docify(a->type);

   818         if (!a->name.isEmpty())

   819         {

   820           ol.docify(" ");

   821           ol.docify(a->name);

   822         }

   823         if (a->defval.length()!=0)

   824         {

   825           ol.docify(" = ");

   826           ol.docify(a->defval);

   827         } 

   828         a=al->next();

   829         if (a) ol.docify(", ");

   830       }

   831       ol.docify(">");

   832       ol.pushGeneratorState();

   833       ol.disableAllBut(OutputGenerator::Html);

   834       ol.lineBreak();

   835       ol.popGeneratorState();

   836     }

   837     ol.docify(type.lower()+" "+name);

   838     ol.endSubsubsection();

   839     ol.writeString("\n");

   840   }

   841 }

   842 

   843 void ClassDef::writeBriefDescription(OutputList &ol,bool exampleFlag)

   844 {

   845   if (!briefDescription().isEmpty())

   846   {

   847     ol.startParagraph();

   848     ol.parseDoc(briefFile(),briefLine(),this,0,

   849                 briefDescription(),TRUE,FALSE,0,TRUE,FALSE);

   850     ol.pushGeneratorState();

   851     ol.disable(OutputGenerator::RTF);

   852     ol.writeString(" \n");

   853     ol.enable(OutputGenerator::RTF);

   854 

   855     if (Config_getBool("REPEAT_BRIEF") || 

   856         !documentation().isEmpty() || 

   857         exampleFlag

   858        )

   859     {

   860       ol.disableAllBut(OutputGenerator::Html);

   861       ol.startTextLink(0,"_details");

   862       ol.parseText(theTranslator->trMore());

   863       ol.endTextLink();

   864     }

   865     ol.popGeneratorState();

   866 

   867     //ol.pushGeneratorState();

   868     //ol.disable(OutputGenerator::RTF);

   869     //ol.newParagraph(); // FIXME:PARA

   870     //ol.popGeneratorState();

   871     ol.endParagraph();

   872   }

   873   ol.writeSynopsis();

   874 }

   875 

   876 // write the detailed description for this class

   877 void ClassDef::writeDetailedDescription(OutputList &ol, const QCString &pageType, bool exampleFlag, 

   878                                         const QCString &title)

   879 {

   880   if ((!briefDescription().isEmpty() && Config_getBool("REPEAT_BRIEF")) || 

   881       !documentation().isEmpty() || 

   882       (Config_getBool("SOURCE_BROWSER") && getStartBodyLine()!=-1 && getBodyDef()) ||

   883       exampleFlag)

   884   {

   885     ol.writeRuler();

   886     ol.pushGeneratorState();

   887       ol.disableAllBut(OutputGenerator::Html);

   888       ol.writeAnchor(0,"_details");

   889     ol.popGeneratorState();

   890     ol.startGroupHeader();

   891     ol.parseText(title);

   892     ol.endGroupHeader();

   893 

   894     ol.startTextBlock();

   895     

   896     writeTemplateSpec(ol,this,pageType);

   897     

   898     // repeat brief description

   899     if (!briefDescription().isEmpty() && Config_getBool("REPEAT_BRIEF"))

   900     {

   901       ol.parseDoc(briefFile(),briefLine(),this,0,briefDescription(),FALSE,FALSE);

   902     }

   903     if (!briefDescription().isEmpty() && Config_getBool("REPEAT_BRIEF") &&

   904         !documentation().isEmpty())

   905     {

   906       ol.pushGeneratorState();

   907         ol.disable(OutputGenerator::Man);

   908         ol.disable(OutputGenerator::RTF);

   909         //ol.newParagraph(); // FIXME:PARA

   910         ol.enableAll();

   911         ol.disableAllBut(OutputGenerator::Man);

   912         ol.writeString("\n\n");

   913       ol.popGeneratorState();

   914     }

   915     // write documentation

   916     if (!documentation().isEmpty())

   917     {

   918       ol.parseDoc(docFile(),docLine(),this,0,documentation(),TRUE,FALSE);

   919     }

   920     // write type constraints

   921     writeTypeConstraints(ol,this,m_impl->typeConstraints);

   922 

   923     // write examples

   924     if (exampleFlag && m_impl->exampleSDict)

   925     {

   926       ol.startSimpleSect(BaseOutputDocInterface::Examples,0,0,theTranslator->trExamples()+": ");

   927       ol.startDescForItem();

   928       ol.startParagraph();

   929       writeExample(ol,m_impl->exampleSDict);

   930       ol.endParagraph();

   931       ol.endDescForItem();

   932       ol.endSimpleSect();

   933     }

   934     //ol.newParagraph();

   935     writeSourceDef(ol,name());

   936     ol.endTextBlock();

   937   }

   938   else

   939   {

   940     writeTemplateSpec(ol,this,pageType);

   941   }

   942 }

   943     

   944 void ClassDef::showUsedFiles(OutputList &ol)

   945 {

   946   ol.pushGeneratorState();

   947   ol.disable(OutputGenerator::Man);

   948   bool fortranOpt = Config_getBool("OPTIMIZE_FOR_FORTRAN");

   949 

   950   ol.writeRuler();

   951   if (fortranOpt)

   952   {

   953     ol.parseText(theTranslator->trGeneratedFromFilesFortran(

   954           m_impl->isObjC && m_impl->compType==Interface ? Class : m_impl->compType,

   955           m_impl->files.count()==1));

   956   }

   957   else

   958   {

   959     ol.parseText(theTranslator->trGeneratedFromFiles(

   960           m_impl->isObjC && m_impl->compType==Interface ? Class : m_impl->compType,

   961           m_impl->files.count()==1));  

   962   }

   963 

   964 

   965   bool first=TRUE;

   966   const char *file = m_impl->files.first();

   967   while (file)

   968   {

   969     bool ambig;

   970     FileDef *fd=findFileDef(Doxygen::inputNameDict,file,ambig);

   971     if (fd)

   972     {

   973       if (first)

   974       {

   975         first=FALSE;   

   976         ol.startItemList();

   977       }

   978 

   979       ol.startItemListItem();

   980       QCString path=fd->getPath();

   981       if (Config_getBool("FULL_PATH_NAMES"))

   982       {

   983         ol.docify(stripFromPath(path));

   984       }

   985 

   986       QCString fname = fd->name();

   987       if (!fd->getVersion().isEmpty()) // append version if available

   988       {

   989         fname += " (" + fd->getVersion() + ")";

   990       }

   991 

   992       // for HTML 

   993       ol.pushGeneratorState();

   994       ol.disableAllBut(OutputGenerator::Html);

   995       if (fd->generateSourceFile())

   996       {

   997         ol.writeObjectLink(0,fd->getSourceFileBase(),0,fname);

   998       }

   999       else if (fd->isLinkable())

  1000       {

  1001         ol.writeObjectLink(fd->getReference(),fd->getOutputFileBase(),0,

  1002             fname);

  1003       }

  1004       else

  1005       {

  1006         ol.docify(fname);

  1007       }

  1008       ol.popGeneratorState();

  1009 

  1010       // for other output formats

  1011       ol.pushGeneratorState();

  1012       ol.disable(OutputGenerator::Html);

  1013       if (fd->isLinkable())

  1014       {

  1015         ol.writeObjectLink(fd->getReference(),fd->getOutputFileBase(),0,

  1016             fname);

  1017       }

  1018       else

  1019       {

  1020         ol.docify(fname);

  1021       }

  1022       ol.popGeneratorState();

  1023 

  1024       ol.endItemListItem();

  1025     }

  1026     file=m_impl->files.next();

  1027   }

  1028   if (!first) ol.endItemList();

  1029 

  1030   ol.popGeneratorState();

  1031 }

  1032 

  1033 

  1034 void ClassDef::writeInheritanceGraph(OutputList &ol)

  1035 {

  1036   // count direct inheritance relations

  1037   int count=0;

  1038   BaseClassDef *ibcd;

  1039   if (m_impl->inheritedBy)

  1040   {

  1041     ibcd=m_impl->inheritedBy->first();

  1042     while (ibcd)

  1043     {

  1044       ClassDef *icd=ibcd->classDef;

  1045       if ( icd->isVisibleInHierarchy()) count++;

  1046       ibcd=m_impl->inheritedBy->next();

  1047     }

  1048   }

  1049   if (m_impl->inherits)

  1050   {

  1051     ibcd=m_impl->inherits->first();

  1052     while (ibcd)

  1053     {

  1054       ClassDef *icd=ibcd->classDef;

  1055       if ( icd->isVisibleInHierarchy()) count++;

  1056       ibcd=m_impl->inherits->next();

  1057     }

  1058   }

  1059 

  1060   

  1061   bool renderDiagram = FALSE;

  1062   if (Config_getBool("HAVE_DOT") && Config_getBool("CLASS_DIAGRAMS"))

  1063     // write class diagram using dot

  1064   {

  1065     DotClassGraph inheritanceGraph(this,DotNode::Inheritance);

  1066     if (!inheritanceGraph.isTrivial() && !inheritanceGraph.isTooBig())

  1067     {

  1068       ol.pushGeneratorState();

  1069       ol.disable(OutputGenerator::Man);

  1070       ol.startDotGraph();

  1071       ol.parseText(theTranslator->trClassDiagram(displayName()));

  1072       ol.endDotGraph(inheritanceGraph);

  1073       ol.popGeneratorState();

  1074       renderDiagram = TRUE;

  1075     }

  1076   }

  1077   else if (Config_getBool("CLASS_DIAGRAMS") && count>0) 

  1078     // write class diagram using build-in generator

  1079   {

  1080     ClassDiagram diagram(this); // create a diagram of this class.

  1081     ol.startClassDiagram();

  1082     ol.disable(OutputGenerator::Man);

  1083     ol.parseText(theTranslator->trClassDiagram(displayName()));

  1084     ol.enable(OutputGenerator::Man);

  1085     ol.endClassDiagram(diagram,getOutputFileBase(),displayName());

  1086     renderDiagram = TRUE;

  1087   } 

  1088 

  1089   if (renderDiagram) // if we already show the inheritance relations graphically,

  1090                      // then hide the text version

  1091   {

  1092     ol.disableAllBut(OutputGenerator::Man);

  1093   }

  1094 

  1095   if (m_impl->inherits && (count=m_impl->inherits->count())>0)

  1096   {

  1097     ol.startParagraph();

  1098     //parseText(ol,theTranslator->trInherits()+" ");

  1099 

  1100     QCString inheritLine = theTranslator->trInheritsList(m_impl->inherits->count());

  1101     QRegExp marker("@[0-9]+");

  1102     int index=0,newIndex,matchLen;

  1103     // now replace all markers in inheritLine with links to the classes

  1104     while ((newIndex=marker.match(inheritLine,index,&matchLen))!=-1)

  1105     {

  1106       ol.parseText(inheritLine.mid(index,newIndex-index));

  1107       bool ok;

  1108       uint entryIndex = inheritLine.mid(newIndex+1,matchLen-1).toUInt(&ok);

  1109       BaseClassDef *bcd=m_impl->inherits->at(entryIndex);

  1110       if (ok && bcd)

  1111       {

  1112         ClassDef *cd=bcd->classDef;

  1113 

  1114         // use the class name but with the template arguments as given

  1115         // in the inheritance relation

  1116         QCString displayName = insertTemplateSpecifierInScope(

  1117             cd->name(),bcd->templSpecifiers);

  1118 

  1119         if (cd->isLinkable())

  1120         {

  1121           if (!Config_getString("GENERATE_TAGFILE").isEmpty()) 

  1122           {

  1123             Doxygen::tagFile << "    <base";

  1124             if (bcd->prot==Protected)

  1125             {

  1126               Doxygen::tagFile << " protection=\"protected\"";

  1127             }

  1128             else if (bcd->prot==Private)

  1129             {

  1130               Doxygen::tagFile << " protection=\"private\"";

  1131             }

  1132             if (bcd->virt==Virtual)

  1133             {

  1134               Doxygen::tagFile << " virtualness=\"virtual\"";