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

     2  *

     3  * 

     4  *

     5  *

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

     7  *

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

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

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

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

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

    13  *

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

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

    16  *

    17  */

    18 

    19 #include <stdio.h>

    20 #include <stdlib.h>

    21 

    22 #include <qfile.h>

    23 #include <qfileinfo.h>

    24 #include <qcstring.h>

    25 #include <qstack.h>

    26 #include <qdict.h>

    27 #include <qregexp.h>

    28 #include <ctype.h>

    29 

    30 #include "doxygen.h"

    31 #include "debug.h"

    32 #include "util.h"

    33 #include "pagedef.h"

    34 

    35 #include "docparser.h"

    36 #include "doctokenizer.h"

    37 #include "cmdmapper.h"

    38 #include "printdocvisitor.h"

    39 #include "message.h"

    40 #include "section.h"

    41 #include "searchindex.h"

    42 #include "language.h"

    43 #include "portable.h"

    44 

    45 // debug off

    46 #define DBG(x) do {} while(0)

    47 

    48 // debug to stdout

    49 //#define DBG(x) printf x

    50 

    51 // debug to stderr

    52 //#define myprintf(x...) fprintf(stderr,x)

    53 //#define DBG(x) myprintf x

    54 

    55 #define INTERNAL_ASSERT(x) do {} while(0)

    56 //#define INTERNAL_ASSERT(x) if (!(x)) DBG(("INTERNAL_ASSERT(%s) failed retval=0x%x: file=%s line=%d\n",#x,retval,__FILE__,__LINE__)); 

    57 

    58 //---------------------------------------------------------------------------

    59 

    60 static const char *sectionLevelToName[] = 

    61 {

    62   "page",

    63   "section",

    64   "subsection",

    65   "subsubsection",

    66   "paragraph"

    67 };

    68 

    69 //---------------------------------------------------------------------------

    70 

    71 // Parser state: global variables during a call to validatingParseDoc

    72 static Definition *           g_scope;

    73 static QString                g_context;

    74 static bool                   g_inSeeBlock;

    75 static bool                   g_insideHtmlLink;

    76 static QStack<DocNode>        g_nodeStack;

    77 static QStack<DocStyleChange> g_styleStack;

    78 static QStack<DocStyleChange> g_initialStyleStack;

    79 static QList<Definition>      g_copyStack;

    80 static QString                g_fileName;

    81 static QString                g_relPath;

    82 

    83 static bool                   g_hasParamCommand;

    84 static bool                   g_hasReturnCommand;

    85 static QDict<void>            g_paramsFound;

    86 static MemberDef *            g_memberDef;

    87 static bool                   g_isExample;

    88 static QCString               g_exampleName;

    89 static SectionDict *          g_sectionDict;

    90 static QCString               g_searchUrl;

    91 

    92 static QString                g_includeFileText;

    93 static uint                   g_includeFileOffset;

    94 static uint                   g_includeFileLength;

    95 

    96 // parser's context to store all global variables

    97 struct DocParserContext

    98 {

    99   Definition *scope;

   100   QString context;

   101   bool inSeeBlock;

   102   bool insideHtmlLink;

   103   QStack<DocNode> nodeStack;

   104   QStack<DocStyleChange> styleStack;

   105   QStack<DocStyleChange> initialStyleStack;

   106   QList<Definition> copyStack;

   107   QString fileName;

   108   QString relPath;

   109 

   110   bool         hasParamCommand;

   111   bool         hasReturnCommand;

   112   MemberDef *  memberDef;

   113   QDict<void>  paramsFound;

   114   bool         isExample;

   115   QCString     exampleName;

   116   SectionDict *sectionDict;

   117   QCString     searchUrl;

   118 

   119   QString  includeFileText;

   120   uint     includeFileOffset;

   121   uint     includeFileLength;

   122 

   123   TokenInfo *token;

   124 };

   125 

   126 static QStack<DocParserContext> g_parserStack;

   127 

   128 //---------------------------------------------------------------------------

   129 

   130 static void docParserPushContext(bool saveParamInfo=TRUE)

   131 {

   132   //QCString indent;

   133   //indent.fill(' ',g_parserStack.count()*2+2);

   134   //printf("%sdocParserPushContext() count=%d\n",indent.data(),g_nodeStack.count());

   135 

   136   doctokenizerYYpushContext();

   137   DocParserContext *ctx   = new DocParserContext;

   138   ctx->scope              = g_scope;

   139   ctx->context            = g_context;

   140   ctx->inSeeBlock         = g_inSeeBlock;

   141   ctx->insideHtmlLink     = g_insideHtmlLink;

   142   ctx->nodeStack          = g_nodeStack;

   143   ctx->styleStack         = g_styleStack;

   144   ctx->initialStyleStack  = g_initialStyleStack;

   145   ctx->copyStack          = g_copyStack;

   146   ctx->fileName           = g_fileName;

   147   ctx->relPath            = g_relPath;

   148 

   149   if (saveParamInfo)

   150   {

   151     ctx->hasParamCommand    = g_hasParamCommand;

   152     ctx->hasReturnCommand   = g_hasReturnCommand;

   153     ctx->paramsFound        = g_paramsFound;

   154   }

   155 

   156   ctx->memberDef          = g_memberDef;

   157   ctx->isExample          = g_isExample;

   158   ctx->exampleName        = g_exampleName;

   159   ctx->sectionDict        = g_sectionDict;

   160   ctx->searchUrl          = g_searchUrl;

   161 

   162   ctx->includeFileText    = g_includeFileText;

   163   ctx->includeFileOffset  = g_includeFileOffset;

   164   ctx->includeFileLength  = g_includeFileLength;

   165   

   166   ctx->token              = g_token;

   167   g_token = new TokenInfo;

   168 

   169   g_parserStack.push(ctx);

   170 }

   171 

   172 static void docParserPopContext(bool keepParamInfo=FALSE)

   173 {

   174   DocParserContext *ctx = g_parserStack.pop();

   175   g_scope               = ctx->scope;

   176   g_context             = ctx->context;

   177   g_inSeeBlock          = ctx->inSeeBlock;

   178   g_insideHtmlLink      = ctx->insideHtmlLink;

   179   g_nodeStack           = ctx->nodeStack;

   180   g_styleStack          = ctx->styleStack;

   181   g_initialStyleStack   = ctx->initialStyleStack;

   182   g_copyStack           = ctx->copyStack;

   183   g_fileName            = ctx->fileName;

   184   g_relPath             = ctx->relPath;

   185 

   186   if (!keepParamInfo)

   187   {

   188     g_hasParamCommand     = ctx->hasParamCommand;

   189     g_hasReturnCommand    = ctx->hasReturnCommand;

   190     g_paramsFound         = ctx->paramsFound;

   191   }

   192   g_memberDef           = ctx->memberDef;

   193   g_isExample           = ctx->isExample;

   194   g_exampleName         = ctx->exampleName;

   195   g_sectionDict         = ctx->sectionDict;

   196   g_searchUrl           = ctx->searchUrl;

   197 

   198   g_includeFileText     = ctx->includeFileText;

   199   g_includeFileOffset   = ctx->includeFileOffset;

   200   g_includeFileLength   = ctx->includeFileLength;

   201 

   202   delete g_token;

   203   g_token               = ctx->token;

   204 

   205   delete ctx;

   206   doctokenizerYYpopContext();

   207 

   208   //QCString indent;

   209   //indent.fill(' ',g_parserStack.count()*2+2);

   210   //printf("%sdocParserPopContext() count=%d\n",indent.data(),g_nodeStack.count());

   211 }

   212 

   213 //---------------------------------------------------------------------------

   214 

   215 /*! search for an image in the imageNameDict and if found

   216  * copies the image to the output directory (which depends on the \a type

   217  * parameter).

   218  */

   219 static QCString findAndCopyImage(const char *fileName,DocImage::Type type)

   220 {

   221   QCString result;

   222   bool ambig;

   223   FileDef *fd;

   224   //printf("Search for %s\n",fileName);

   225   if ((fd=findFileDef(Doxygen::imageNameDict,fileName,ambig)))

   226   {

   227     QCString inputFile = fd->absFilePath();

   228     QFile inImage(inputFile);

   229     if (inImage.open(IO_ReadOnly))

   230     {

   231       result = fileName;

   232       int i;

   233       if ((i=result.findRev('/'))!=-1 || (i=result.findRev('\\'))!=-1)

   234       {

   235 	result = result.right(result.length()-i-1);

   236       }

   237       //printf("fileName=%s result=%s\n",fileName,result.data());

   238       QCString outputDir;

   239       switch(type)

   240       {

   241         case DocImage::Html: 

   242 	  if (!Config_getBool("GENERATE_HTML")) return result;

   243 	  outputDir = Config_getString("HTML_OUTPUT");

   244 	  break;

   245         case DocImage::Latex: 

   246 	  if (!Config_getBool("GENERATE_LATEX")) return result;

   247 	  outputDir = Config_getString("LATEX_OUTPUT");

   248 	  break;

   249         case DocImage::Rtf:

   250 	  if (!Config_getBool("GENERATE_RTF")) return result;

   251 	  outputDir = Config_getString("RTF_OUTPUT");

   252 	  break;

   253       }

   254       QCString outputFile = outputDir+"/"+result;

   255       if (outputFile!=inputFile) // prevent copying to ourself

   256       {

   257         QFile outImage(outputFile.data());

   258         if (outImage.open(IO_WriteOnly)) // copy the image

   259         {

   260           char *buffer = new char[inImage.size()];

   261           inImage.readBlock(buffer,inImage.size());

   262           outImage.writeBlock(buffer,inImage.size());

   263           outImage.flush();

   264           delete[] buffer;

   265           if (type==DocImage::Html) Doxygen::indexList.addImageFile(result);

   266         }

   267         else

   268         {

   269           warn_doc_error(g_fileName,doctokenizerYYlineno,

   270               "Warning: could not write output image %s",outputFile.data());

   271         }

   272       }

   273     }

   274     else

   275     {

   276       warn_doc_error(g_fileName,doctokenizerYYlineno,

   277 	  "Warning: could not open image %s",fileName);

   278     }

   279 

   280     if (type==DocImage::Latex && Config_getBool("USE_PDFLATEX") && 

   281 	fd->name().right(4)==".eps"

   282        )

   283     { // we have an .eps image in pdflatex mode => convert it to a pdf.

   284       QCString outputDir = Config_getString("LATEX_OUTPUT");

   285       QCString baseName  = fd->name().left(fd->name().length()-4);

   286       QCString epstopdfArgs(4096);

   287       epstopdfArgs.sprintf("\"%s/%s.eps\" --outfile=\"%s/%s.pdf\"",

   288                            outputDir.data(), baseName.data(),

   289 			   outputDir.data(), baseName.data());

   290       if (portable_system("epstopdf",epstopdfArgs)!=0)

   291       {

   292 	err("Error: Problems running epstopdf. Check your TeX installation!\n");

   293       }

   294       return baseName;

   295     }

   296   }

   297   else if (ambig)

   298   {

   299     QCString text;

   300     text.sprintf("Warning: image file name %s is ambigious.\n",fileName);

   301     text+="Possible candidates:\n";

   302     text+=showFileDefMatches(Doxygen::imageNameDict,fileName);

   303     warn_doc_error(g_fileName,doctokenizerYYlineno,text);

   304   }

   305   else

   306   {

   307     result=fileName;

   308     if (result.left(5)!="http:" && result.left(6)!="https:")

   309     {

   310       warn_doc_error(g_fileName,doctokenizerYYlineno,

   311            "Warning: image file %s is not found in IMAGE_PATH: "  

   312 	   "assuming external image.",fileName

   313           );

   314     }

   315   }

   316   return result;

   317 }

   318 

   319 /*! Collects the parameters found with \@param or \@retval commands

   320  *  in a global list g_paramsFound. If \a isParam is set to TRUE

   321  *  and the parameter is not an actual parameter of the current

   322  *  member g_memberDef, then a warning is raised (unless warnings

   323  *  are disabled altogether).

   324  */

   325 static void checkArgumentName(const QString &name,bool isParam)

   326 {                

   327   if (!Config_getBool("WARN_IF_DOC_ERROR")) return;

   328   if (g_memberDef==0) return; // not a member

   329   LockingPtr<ArgumentList> al=g_memberDef->isDocsForDefinition() ? 

   330 		   g_memberDef->argumentList() :

   331                    g_memberDef->declArgumentList();

   332   //printf("isDocsForDefinition()=%d\n",g_memberDef->isDocsForDefinition());

   333   if (al==0) return; // no argument list

   334 

   335   static QRegExp re("[a-zA-Z0-9_\\x80-\\xFF]+\\.*");

   336   int p=0,i=0,l;

   337   while ((i=re.match(name,p,&l))!=-1) // to handle @param x,y

   338   {

   339     QString aName=name.mid(i,l);

   340     //printf("aName=`%s'\n",aName.data());

   341     ArgumentListIterator ali(*al);

   342     Argument *a;

   343     bool found=FALSE;

   344     for (ali.toFirst();(a=ali.current());++ali)

   345     {

   346       QString argName = g_memberDef->isDefine() ? a->type : a->name;

   347       argName=argName.stripWhiteSpace();

   348       //printf("argName=`%s'\n",argName.data());

   349       if (argName.right(3)=="...") argName=argName.left(argName.length()-3);

   350       if (aName==argName) 

   351       {

   352 	//printf("adding `%s'\n",aName.data());

   353 	g_paramsFound.insert(aName,(void *)(0x8));

   354 	found=TRUE;

   355 	break;

   356       }

   357     }

   358     if (!found && isParam)

   359     {

   360       //printf("member type=%d\n",memberDef->memberType());

   361       QString scope=g_memberDef->getScopeString();

   362       if (!scope.isEmpty()) scope+="::"; else scope="";

   363       QString inheritedFrom = "";

   364       QString docFile = g_memberDef->docFile();

   365       int docLine = g_memberDef->docLine();

   366       MemberDef *inheritedMd = g_memberDef->inheritsDocsFrom();

   367       if (inheritedMd) // documentation was inherited

   368       {

   369         inheritedFrom.sprintf(" inherited from member %s at line "

   370             "%d in file %s",inheritedMd->name().data(),

   371             inheritedMd->docLine(),inheritedMd->docFile().data());

   372         docFile = g_memberDef->getDefFileName();

   373         docLine = g_memberDef->getDefLine();

   374         

   375       }

   376       warn_doc_error(docFile,docLine,

   377 	  "Warning: argument '%s' of command @param "

   378 	  "is not found in the argument list of %s%s%s%s",

   379 	  aName.data(),scope.data(),g_memberDef->name().data(),

   380 	  argListToString(al.pointer()).data(),inheritedFrom.data());

   381     }

   382     p=i+l;

   383   }

   384 }

   385 

   386 /*! Checks if the parameters that have been specified using \@param are

   387  *  indeed all paramters.

   388  *  Must be called after checkArgumentName() has been called for each

   389  *  argument.

   390  */

   391 static void checkUndocumentedParams()

   392 {

   393   if (g_memberDef && g_hasParamCommand && Config_getBool("WARN_IF_DOC_ERROR"))

   394   {

   395     LockingPtr<ArgumentList> al=g_memberDef->isDocsForDefinition() ? 

   396       g_memberDef->argumentList() :

   397       g_memberDef->declArgumentList();

   398     if (al!=0)

   399     {

   400       ArgumentListIterator ali(*al);

   401       Argument *a;

   402       bool found=FALSE;

   403       for (ali.toFirst();(a=ali.current());++ali)

   404       {

   405         QString argName = g_memberDef->isDefine() ? a->type : a->name;

   406         argName=argName.stripWhiteSpace();

   407         if (argName.right(3)=="...") argName=argName.left(argName.length()-3);

   408         if (getLanguageFromFileName(g_memberDef->getDefFileName())==SrcLangExt_Python && argName=="self")

   409         { 

   410           // allow undocumented self parameter for Python

   411         }

   412         else if (!argName.isEmpty() && g_paramsFound.find(argName)==0 && a->docs.isEmpty()) 

   413         {

   414           found = TRUE;

   415           break;

   416         }

   417       }

   418       if (found)

   419       {

   420         bool first=TRUE;

   421         QString errMsg=

   422             "Warning: The following parameters of "+

   423             QString(g_memberDef->qualifiedName()) + 

   424             QString(argListToString(al.pointer())) +

   425             " are not documented:\n";

   426         for (ali.toFirst();(a=ali.current());++ali)

   427         {

   428           QString argName = g_memberDef->isDefine() ? a->type : a->name;

   429           argName=argName.stripWhiteSpace();

   430           if (getLanguageFromFileName(g_memberDef->getDefFileName())==SrcLangExt_Python && argName=="self")

   431           { 

   432             // allow undocumented self parameter for Python

   433           }

   434           else if (!argName.isEmpty() && g_paramsFound.find(argName)==0) 

   435           {

   436             if (!first)

   437             {

   438               errMsg+="\n";

   439             }

   440             else

   441             {

   442               first=FALSE;

   443             }

   444             errMsg+="  parameter '"+argName+"'";

   445           }

   446         }

   447         if (g_memberDef->inheritsDocsFrom())

   448         {

   449            warn_doc_error(g_memberDef->getDefFileName(),

   450                           g_memberDef->getDefLine(),

   451                           substitute(errMsg,"%","%%"));

   452         }

   453         else

   454         {

   455            warn_doc_error(g_memberDef->docFile(),

   456                           g_memberDef->docLine(),

   457                           substitute(errMsg,"%","%%"));

   458         }

   459       }

   460     }

   461   }

   462 }

   463 

   464 /*! Check if a member has documentation for its parameter and or return

   465  *  type, if applicable. If found this will be stored in the member, this

   466  *  is needed as a member can have brief and detailed documentation, while

   467  *  only one of these needs to document the parameters.

   468  */

   469 static void detectNoDocumentedParams()

   470 {

   471   if (g_memberDef && Config_getBool("WARN_NO_PARAMDOC"))

   472   {

   473     LockingPtr<ArgumentList> al     = g_memberDef->argumentList();

   474     LockingPtr<ArgumentList> declAl = g_memberDef->declArgumentList();

   475     QString returnType   = g_memberDef->typeString();

   476     bool isPython = getLanguageFromFileName(g_memberDef->getDefFileName())==SrcLangExt_Python;

   477 

   478     if (!g_memberDef->hasDocumentedParams() &&

   479         g_hasParamCommand)

   480     {

   481       //printf("%s->setHasDocumentedParams(TRUE);\n",g_memberDef->name().data());

   482       g_memberDef->setHasDocumentedParams(TRUE);

   483     }

   484     else if (!g_memberDef->hasDocumentedParams())

   485     {

   486       bool allDoc=TRUE; // no paramater => all parameters are documented

   487       if ( // member has parameters

   488              al!=0 &&       // but the member has a parameter list

   489              al->count()>0  // with at least one parameter (that is not void)

   490          )

   491       {

   492         ArgumentListIterator ali(*al);

   493         Argument *a;

   494 

   495         // see if all parameters have documentation

   496         for (ali.toFirst();(a=ali.current()) && allDoc;++ali)

   497         {

   498           if (!a->name.isEmpty() && a->type!="void" &&

   499               !(isPython && a->name=="self")

   500              )

   501           {

   502             allDoc = !a->docs.isEmpty();

   503           }

   504           //printf("a->type=%s a->name=%s doc=%s\n",

   505           //        a->type.data(),a->name.data(),a->docs.data());

   506         }

   507         if (!allDoc && declAl!=0) // try declaration arguments as well

   508         {

   509           allDoc=TRUE;

   510           ArgumentListIterator ali(*declAl);

   511           Argument *a;

   512           for (ali.toFirst();(a=ali.current()) && allDoc;++ali)

   513           {

   514             if (!a->name.isEmpty() && a->type!="void" &&

   515                 !(isPython && a->name=="self")

   516                )

   517             {

   518               allDoc = !a->docs.isEmpty();

   519             }

   520             //printf("a->name=%s doc=%s\n",a->name.data(),a->docs.data());

   521           }

   522         }

   523       }

   524       if (allDoc) 

   525       {

   526         //printf("%s->setHasDocumentedParams(TRUE);\n",g_memberDef->name().data());

   527         g_memberDef->setHasDocumentedParams(TRUE);

   528       }

   529     }

   530     //printf("Member %s hasReturnCommand=%d\n",g_memberDef->name().data(),g_hasReturnCommand);

   531     if (!g_memberDef->hasDocumentedReturnType() && // docs not yet found

   532         g_hasReturnCommand)

   533     {

   534       g_memberDef->setHasDocumentedReturnType(TRUE);

   535     }

   536     else if ( // see if return needs to documented 

   537         g_memberDef->hasDocumentedReturnType() ||

   538         returnType.isEmpty() ||          // empty return type

   539         returnType.find("void")!=-1  ||  // void return type

   540         !g_memberDef->isConstructor() || // a constructor

   541         !g_memberDef->isDestructor()     // or destructor

   542        )

   543     {

   544       g_memberDef->setHasDocumentedReturnType(TRUE);

   545     }

   546        

   547   }

   548 }

   549 

   550 

   551 //---------------------------------------------------------------------------

   552 

   553 /*! Strips known html and tex extensions from \a text. */

   554 static QString stripKnownExtensions(const char *text)

   555 {

   556   QString result=text;

   557   if (result.right(4)==".tex")

   558   {

   559     result=result.left(result.length()-4);

   560   }

   561   else if (result.right(Doxygen::htmlFileExtension.length())==

   562          QString(Doxygen::htmlFileExtension)) 

   563   {

   564     result=result.left(result.length()-Doxygen::htmlFileExtension.length());

   565   }

   566   return result;

   567 }

   568 

   569 

   570 //---------------------------------------------------------------------------

   571 

   572 /*! Returns TRUE iff node n is a child of a preformatted node */

   573 static bool insidePRE(DocNode *n)

   574 {

   575   while (n)

   576   {

   577     if (n->isPreformatted()) return TRUE;

   578     n=n->parent();

   579   }

   580   return FALSE;

   581 }

   582 

   583 //---------------------------------------------------------------------------

   584 

   585 /*! Returns TRUE iff node n is a child of a html list item node */

   586 static bool insideLI(DocNode *n)

   587 {

   588   while (n)

   589   {

   590     if (n->kind()==DocNode::Kind_HtmlListItem) return TRUE;

   591     n=n->parent();

   592   }

   593   return FALSE;

   594 }

   595 

   596 //---------------------------------------------------------------------------

   597 

   598 /*! Returns TRUE iff node n is a child of a unordered html list node */

   599 static bool insideUL(DocNode *n)

   600 {

   601   while (n)

   602   {

   603     if (n->kind()==DocNode::Kind_HtmlList && 

   604         ((DocHtmlList *)n)->type()==DocHtmlList::Unordered) return TRUE;

   605     n=n->parent();

   606   }

   607   return FALSE;

   608 }

   609 

   610 //---------------------------------------------------------------------------

   611 

   612 /*! Returns TRUE iff node n is a child of a ordered html list node */

   613 static bool insideOL(DocNode *n)

   614 {

   615   while (n)

   616   {

   617     if (n->kind()==DocNode::Kind_HtmlList && 

   618         ((DocHtmlList *)n)->type()==DocHtmlList::Ordered) return TRUE;

   619     n=n->parent();

   620   }

   621   return FALSE;

   622 }

   623 

   624 //---------------------------------------------------------------------------

   625 

   626 static bool insideTable(DocNode *n)

   627 {

   628   while (n)

   629   {

   630     if (n->kind()==DocNode::Kind_HtmlTable) return TRUE;

   631     n=n->parent();

   632   }

   633   return FALSE;

   634 }

   635 

   636 //---------------------------------------------------------------------------

   637 

   638 ///*! Returns TRUE iff node n is a child of a language node */

   639 //static bool insideLang(DocNode *n)

   640 //{

   641 //  while (n)

   642 //  {

   643 //    if (n->kind()==DocNode::Kind_Language) return TRUE;

   644 //    n=n->parent();

   645 //  }

   646 //  return FALSE;

   647 //}

   648 

   649 

   650 //---------------------------------------------------------------------------

   651 

   652 /*! Looks for a documentation block with name commandName in the current

   653  *  context (g_context). The resulting documentation string is

   654  *  put in pDoc, the definition in which the documentation was found is

   655  *  put in pDef.

   656  *  @retval TRUE if name was found.

   657  *  @retval FALSE if name was not found.

   658  */

   659 static bool findDocsForMemberOrCompound(const char *commandName,

   660                                  QString *pDoc,

   661                                  QString *pBrief,

   662                                  Definition **pDef)

   663 {

   664   //printf("findDocsForMemberOrCompound(%s)\n",commandName);

   665   *pDoc="";

   666   *pBrief="";

   667   *pDef=0;

   668   QString cmdArg=substitute(commandName,"#","::");

   669   int l=cmdArg.length();

   670   if (l==0) return FALSE;

   671 

   672   int funcStart=cmdArg.find('(');

   673   if (funcStart==-1) funcStart=l;

   674 

   675   QString name=removeRedundantWhiteSpace(cmdArg.left(funcStart).latin1());

   676   QString args=cmdArg.right(l-funcStart);

   677 

   678   // try if the link is to a member

   679   MemberDef    *md=0;

   680   ClassDef     *cd=0;

   681   FileDef      *fd=0;

   682   NamespaceDef *nd=0;

   683   GroupDef     *gd=0;

   684   PageDef      *pd=0;

   685   bool found = getDefs(

   686       g_context.find('.')==-1?g_context.latin1():"", // `find('.') is a hack to detect files

   687       name.latin1(),

   688       args.isEmpty()?0:args.latin1(),

   689       md,cd,fd,nd,gd,FALSE,0,TRUE);

   690   //printf("found=%d context=%s name=%s\n",found,g_context.data(),name.data());

   691   if (found && md)

   692   {

   693     *pDoc=md->documentation();

   694     *pBrief=md->briefDescription();

   695     *pDef=md;

   696     return TRUE;

   697   }

   698 

   699 

   700   int scopeOffset=g_context.length();

   701   do // for each scope

   702   {

   703     QString fullName=cmdArg;

   704     if (scopeOffset>0)

   705     {

   706       fullName.prepend(g_context.left(scopeOffset)+"::");

   707     }

   708     //printf("Trying fullName=`%s'\n",fullName.data());

   709 

   710     // try class, namespace, group, page, file reference

   711     cd = Doxygen::classSDict->find(fullName);

   712     if (cd) // class 

   713     {

   714       *pDoc=cd->documentation();

   715       *pBrief=cd->briefDescription();

   716       *pDef=cd;

   717       return TRUE;

   718     }

   719     nd = Doxygen::namespaceSDict->find(fullName);

   720     if (nd) // namespace

   721     {

   722       *pDoc=nd->documentation();

   723       *pBrief=nd->briefDescription();

   724       *pDef=nd;

   725       return TRUE;

   726     }

   727     gd = Doxygen::groupSDict->find(cmdArg);

   728     if (gd) // group

   729     {

   730       *pDoc=gd->documentation();

   731       *pBrief=gd->briefDescription();

   732       *pDef=gd;

   733       return TRUE;

   734     }

   735     pd = Doxygen::pageSDict->find(cmdArg);

   736     if (pd) // page

   737     {

   738       *pDoc=pd->documentation();

   739       *pBrief=pd->briefDescription();

   740       *pDef=pd;

   741       return TRUE;

   742     }

   743     bool ambig;

   744     fd = findFileDef(Doxygen::inputNameDict,cmdArg,ambig);

   745     if (fd && !ambig) // file

   746     {

   747       *pDoc=fd->documentation();

   748       *pBrief=fd->briefDescription();

   749       *pDef=fd;

   750       return TRUE;

   751     }

   752 

   753     if (scopeOffset==0)

   754     {

   755       scopeOffset=-1;

   756     }

   757     else

   758     {

   759       scopeOffset = g_context.findRev("::",scopeOffset-1);

   760       if (scopeOffset==-1) scopeOffset=0;

   761     }

   762   } while (scopeOffset>=0);

   763 

   764   

   765   return FALSE;

   766 }

   767 //---------------------------------------------------------------------------

   768 

   769 // forward declaration

   770 static bool defaultHandleToken(DocNode *parent,int tok, 

   771                                QList<DocNode> &children,bool

   772                                handleWord=TRUE);

   773 

   774 

   775 static int handleStyleArgument(DocNode *parent,QList<DocNode> &children,

   776                                const QString &cmdName)

   777 {

   778   DBG(("handleStyleArgument(%s)\n",cmdName.data()));

   779   QString tokenName = g_token->name;

   780   int tok=doctokenizerYYlex();

   781   if (tok!=TK_WHITESPACE)

   782   {

   783     warn_doc_error(g_fileName,doctokenizerYYlineno,"Warning: expected whitespace after %s command",

   784 	cmdName.data());

   785     return tok;

   786   }

   787   while ((tok=doctokenizerYYlex()) && 

   788           tok!=TK_WHITESPACE && 

   789           tok!=TK_NEWPARA &&

   790           tok!=TK_LISTITEM && 

   791           tok!=TK_ENDLIST

   792         )

   793   {

   794     static QRegExp specialChar("[.,|()\\[\\]:;\\?]");

   795     if (tok==TK_WORD && g_token->name.length()==1 && 

   796         g_token->name.find(specialChar)!=-1)

   797     {

   798       // special character that ends the markup command

   799       return tok;

   800     }

   801     if (!defaultHandleToken(parent,tok,children))

   802     {

   803       switch (tok)

   804       {

   805         case TK_COMMAND: 

   806 	  warn_doc_error(g_fileName,doctokenizerYYlineno,"Warning: Illegal command \\%s as the argument of a \\%s command",

   807 	       g_token->name.data(),cmdName.data());

   808           break;

   809         case TK_SYMBOL: 

   810 	  warn_doc_error(g_fileName,doctokenizerYYlineno,"Warning: Unsupported symbol %s found while handling command %s",

   811                g_token->name.data(),cmdName.data());

   812           break;

   813         case TK_HTMLTAG:

   814           if (insideLI(parent) && Mappers::htmlTagMapper->map(g_token->name) && g_token->endTag)

   815           { // ignore </li> as the end of a style command

   816             continue; 

   817           }

   818           return tok;

   819           break;

   820         default:

   821 	  warn_doc_error(g_fileName,doctokenizerYYlineno,"Warning: Unexpected token %s while handling command %s",

   822 	       tokToString(tok),cmdName.data());

   823           break;

   824       }

   825       break;

   826     }

   827   }

   828   DBG(("handleStyleArgument(%s) end tok=%x\n",cmdName.data(),tok));

   829   return (tok==TK_NEWPARA || tok==TK_LISTITEM || tok==TK_ENDLIST

   830          ) ? tok : RetVal_OK; 

   831 }

   832 

   833 /*! Called when a style change starts. For instance a \<b\> command is

   834  *  encountered.

   835  */

   836 static void handleStyleEnter(DocNode *parent,QList<DocNode> &children,

   837           DocStyleChange::Style s,const HtmlAttribList *attribs)

   838 {

   839   DBG(("HandleStyleEnter\n"));

   840   DocStyleChange *sc= new DocStyleChange(parent,g_nodeStack.count(),s,TRUE,attribs);

   841   children.append(sc);

   842   g_styleStack.push(sc);

   843 }

   844 

   845 /*! Called when a style change ends. For instance a \</b\> command is

   846  *  encountered.

   847  */

   848 static void handleStyleLeave(DocNode *parent,QList<DocNode> &children,

   849          DocStyleChange::Style s,const char *tagName)

   850 {

   851   DBG(("HandleStyleLeave\n"));

   852   if (g_styleStack.isEmpty() ||                           // no style change

   853       g_styleStack.top()->style()!=s ||                   // wrong style change

   854       g_styleStack.top()->position()!=g_nodeStack.count() // wrong position

   855      )

   856   {

   857     if (g_styleStack.isEmpty())

   858     {

   859       warn_doc_error(g_fileName,doctokenizerYYlineno,"Warning: found </%s> tag without matching <%s>",

   860           tagName,tagName);

   861     }

   862     else

   863     {

   864       warn_doc_error(g_fileName,doctokenizerYYlineno,"Warning: found </%s> tag while expecting </%s>",

   865           tagName,g_styleStack.top()->styleString());

   866     }

   867   }

   868   else // end the section

   869   {

   870     DocStyleChange *sc= new DocStyleChange(parent,g_nodeStack.count(),s,FALSE);

   871     children.append(sc);

   872     g_styleStack.pop();

   873   }

   874 }

   875 

   876 /*! Called at the end of a paragraph to close all open style changes

   877  *  (e.g. a <b> without a </b>). The closed styles are pushed onto a stack

   878  *  and entered again at the start of a new paragraph.

   879  */

   880 static void handlePendingStyleCommands(DocNode *parent,QList<DocNode> &children)

   881 {

   882   if (!g_styleStack.isEmpty())

   883   {

   884     DocStyleChange *sc = g_styleStack.top();

   885     while (sc && sc->position()>=g_nodeStack.count()) 

   886     { // there are unclosed style modifiers in the paragraph

   887       children.append(new DocStyleChange(parent,g_nodeStack.count(),sc->style(),FALSE));

   888       g_initialStyleStack.push(sc);

   889       g_styleStack.pop();

   890       sc = g_styleStack.top();

   891     }

   892   }

   893 }

   894 

   895 static void handleInitialStyleCommands(DocPara *parent,QList<DocNode> &children)

   896 {

   897   DocStyleChange *sc;

   898   while ((sc=g_initialStyleStack.pop()))

   899   {

   900     handleStyleEnter(parent,children,sc->style(),&sc->attribs());

   901   }

   902 }

   903 

   904 static int handleAHref(DocNode *parent,QList<DocNode> &children,const HtmlAttribList &tagHtmlAttribs)

   905 {

   906   HtmlAttribListIterator li(tagHtmlAttribs);

   907   HtmlAttrib *opt;

   908   int index=0;

   909   int retval = RetVal_OK;

   910   for (li.toFirst();(opt=li.current());++li,++index)

   911   {

   912     if (opt->name=="name") // <a name=label> tag

   913     {

   914       if (!opt->value.isEmpty())

   915       {

   916         DocAnchor *anc = new DocAnchor(parent,opt->value,TRUE);

   917         children.append(anc);

   918         break; // stop looking for other tag attribs

   919       }

   920       else

   921       {

   922         warn_doc_error(g_fileName,doctokenizerYYlineno,"Warning: found <a> tag with name option but without value!");

   923       }

   924     }

   925     else if (opt->name=="href") // <a href=url>..</a> tag

   926     {

   927       // copy attributes

   928       HtmlAttribList attrList = tagHtmlAttribs;

   929       // and remove the href attribute

   930       bool result = attrList.remove(index);

   931       ASSERT(result);

   932       DocHRef *href = new DocHRef(parent,attrList,opt->value);

   933       children.append(href);

   934       g_insideHtmlLink=TRUE;

   935       retval = href->parse();

   936       g_insideHtmlLink=FALSE;

   937       break;

   938     }

   939     else // unsupported option for tag a

   940     {

   941     }

   942   }

   943   return retval;

   944 }

   945 

   946 const char *DocStyleChange::styleString() const

   947 {

   948   switch (m_style)

   949   {

   950     case DocStyleChange::Bold:         return "b"; 

   951     case DocStyleChange::Italic:       return "em"; 

   952     case DocStyleChange::Code:         return "code"; 

   953     case DocStyleChange::Center:       return "center"; 

   954     case DocStyleChange::Small:        return "small"; 

   955     case DocStyleChange::Subscript:    return "subscript"; 

   956     case DocStyleChange::Superscript:  return "superscript"; 

   957     case DocStyleChange::Preformatted: return "pre"; 

   958     case DocStyleChange::Div:          return "div";

   959     case DocStyleChange::Span:         return "span";

   960   }

   961   return "<invalid>";

   962 }

   963 

   964 static void handleUnclosedStyleCommands()

   965 {

   966   if (!g_initialStyleStack.isEmpty())

   967   {

   968     DocStyleChange *sc = g_initialStyleStack.top();

   969     g_initialStyleStack.pop();

   970     handleUnclosedStyleCommands();

   971     warn_doc_error(g_fileName,doctokenizerYYlineno,

   972              "Warning: end of comment block while expecting "

   973              "command </%s>",sc->styleString());

   974   }

   975 }

   976 

   977 

   978 static void handleLinkedWord(DocNode *parent,QList<DocNode> &children)

   979 {

   980   Definition *compound=0;

   981   MemberDef  *member=0;

   982   QString name = linkToText(g_token->name,TRUE);

   983   int len = g_token->name.length();

   984   ClassDef *cd=0;

   985   bool ambig;

   986   FileDef *fd = findFileDef(Doxygen::inputNameDict,g_fileName,ambig);

   987   //printf("handleLinkedWord(%s) g_context=%s\n",name.data(),g_context.data());

   988   if (!g_insideHtmlLink && 

   989       (resolveRef(g_context,g_token->name,g_inSeeBlock,&compound,&member,TRUE,fd)

   990        || (!g_context.isEmpty() &&  // also try with global scope

   991            resolveRef("",g_token->name,g_inSeeBlock,&compound,&member))

   992       )

   993      )

   994   {

   995     //printf("resolveRef %s = %p (linkable?=%d)\n",g_token->name.data(),member,member ? member->isLinkable() : FALSE);

   996     if (member && member->isLinkable()) // member link

   997     {

   998       if (member->isObjCMethod()) 

   999       {

  1000         bool localLink = g_memberDef ? member->getClassDef()==g_memberDef->getClassDef() : FALSE;

  1001         name = member->objCMethodName(localLink,g_inSeeBlock);

  1002       }

  1003       children.append(new 

  1004           DocLinkedWord(parent,name,

  1005             member->getReference(),

  1006             member->getOutputFileBase(),

  1007             member->anchor(),

  1008             member->briefDescriptionAsTooltip()

  1009                        )

  1010                      );

  1011     }

  1012     else if (compound->isLinkable()) // compound link

  1013     {

  1014       if (compound->definitionType()==Definition::TypeFile)

  1015       {

  1016         name=g_token->name;

  1017       }

  1018       else if (compound->definitionType()==Definition::TypeGroup)

  1019       {

  1020         name=((GroupDef*)compound)->groupTitle();

  1021       }

  1022       children.append(new 

  1023           DocLinkedWord(parent,name,

  1024                         compound->getReference(),

  1025                         compound->getOutputFileBase(),

  1026                         "",

  1027                         compound->briefDescriptionAsTooltip()

  1028                        )

  1029                      );

  1030     }

  1031     else if (compound->definitionType()==Definition::TypeFile &&

  1032              ((FileDef*)compound)->generateSourceFile()

  1033             ) // undocumented file that has source code we can link to

  1034     {

  1035       children.append(new 

  1036           DocLinkedWord(parent,g_token->name,

  1037                          compound->getReference(),

  1038                          compound->getSourceFileBase(),

  1039                          "",

  1040                          compound->briefDescriptionAsTooltip()

  1041                        )

  1042                      );

  1043     }

  1044     else // not linkable

  1045     {

  1046       children.append(new DocWord(parent,name));

  1047     }

  1048   }

  1049   else if (!g_insideHtmlLink && len>1 && g_token->name.at(len-1)==':')

  1050   {

  1051     // special case, where matching Foo: fails to be an Obj-C reference, 

  1052     // but Foo itself might be linkable.

  1053     g_token->name=g_token->name.left(len-1);

  1054     handleLinkedWord(parent,children);

  1055     children.append(new DocWord(parent,":"));

  1056   }

  1057   else if (!g_insideHtmlLink && (cd=getClass(g_token->name+"-p")))

  1058   {

  1059     // special case 2, where the token name is not a class, but could

  1060     // be a Obj-C protocol

  1061     children.append(new 

  1062         DocLinkedWord(parent,name,

  1063           cd->getReference(),

  1064           cd->getOutputFileBase(),

  1065           "",

  1066           cd->briefDescriptionAsTooltip()

  1067           ));

  1068   }

  1069   else // normal non-linkable word

  1070   {

  1071     if (g_token->name.at(0)=='#')

  1072     {

  1073       warn_doc_error(g_fileName,doctokenizerYYlineno,"Warning: explicit link request to '%s' could not be resolved",name.data());

  1074     }

  1075     children.append(new DocWord(parent,name));

  1076   }

  1077 }

  1078 

  1079 /* Helper function that deals with the most common tokens allowed in

  1080  * title like sections. 

  1081  * @param parent     Parent node, owner of the children list passed as 

  1082  *                   the third argument. 

  1083  * @param tok        The token to process.

  1084  * @param children   The list of child nodes to which the node representing

  1085  *                   the token can be added.

  1086  * @param handleWord Indicates if word token should be processed

  1087  * @retval TRUE      The token was handled.

  1088  * @retval FALSE     The token was not handled.

  1089  */

  1090 static bool defaultHandleToken(DocNode *parent,int tok, QList<DocNode> &children,bool

  1091     handleWord)

  1092 {

  1093   DBG(("token %s at %d",tokToString(tok),doctokenizerYYlineno));

  1094   if (tok==TK_WORD || tok==TK_LNKWORD || tok==TK_SYMBOL || tok==TK_URL || 

  1095       tok==TK_COMMAND || tok==TK_HTMLTAG

  1096      )

  1097   {

  1098     DBG((" name=%s",g_token->name.data()));

  1099   }

  1100   DBG(("\n"));

  1101 reparsetoken:

  1102   QString tokenName = g_token->name;

  1103   switch (tok)

  1104   {

  1105     case TK_COMMAND: 

  1106       switch (Mappers::cmdMapper->map(tokenName))

  1107       {

  1108         case CMD_BSLASH:

  1109           children.append(new DocSymbol(parent,DocSymbol::BSlash));

  1110           break;

  1111         case CMD_AT:

  1112           children.append(new DocSymbol(parent,DocSymbol::At));

  1113           break;

  1114         case CMD_LESS:

  1115           children.append(new DocSymbol(parent,DocSymbol::Less));

  1116           break;

  1117         case CMD_GREATER:

  1118           children.append(new DocSymbol(parent,DocSymbol::Greater));

  1119           break;

  1120         case CMD_AMP:

  1121           children.append(new DocSymbol(parent,DocSymbol::Amp));

  1122           break;

  1123         case CMD_DOLLAR:

  1124           children.append(new DocSymbol(parent,DocSymbol::Dollar));

  1125           break;

  1126         case CMD_HASH:

  1127           children.append(new DocSymbol(parent,DocSymbol::Hash));

  1128           break;

  1129         case CMD_PERCENT:

  1130           children.append(new DocSymbol(parent,DocSymbol::Percent));

  1131           break;

  1132         case CMD_QUOTE:

  1133           children.append(new DocSymbol(parent,DocSymbol::Quot));

  1134           break;