docparser.h File Reference

#include <stdio.h>
#include <qlist.h>
#include <qcstring.h>
#include "docvisitor.h"
#include "htmlattrib.h"

Go to the source code of this file.

Classes
class	DocNode
class	CompAccept< T >
class	DocWord
class	DocLinkedWord
class	DocURL
class	DocLineBreak
class	DocHorRuler
class	DocAnchor
class	DocCite
class	DocStyleChange
class	DocSymbol
struct	DocSymbol::PerlSymb
class	DocWhiteSpace
class	DocVerbatim
class	DocInclude
class	DocIncOperator
class	DocFormula
class	DocIndexEntry
class	DocCopy
class	DocAutoList
class	DocAutoListItem
class	DocTitle
class	DocXRefItem
class	DocImage
class	DocDotFile
class	DocMscFile
class	DocDiaFile
class	DocVhdlFlow
class	DocLink
class	DocRef
class	DocInternalRef
class	DocHRef
class	DocHtmlHeader
class	DocHtmlDescTitle
class	DocHtmlDescList
class	DocSection
class	DocSecRefItem
class	DocSecRefList
class	DocInternal
class	DocParBlock
class	DocSimpleList
class	DocHtmlList
class	DocSimpleSect
class	DocSimpleSectSep
class	DocParamSect
class	DocPara
class	DocParamList
class	DocSimpleListItem
class	DocHtmlListItem
class	DocHtmlDescData
class	DocHtmlCell
class	DocHtmlCaption
class	DocHtmlRow
class	DocHtmlTable
class	DocHtmlBlockQuote
class	DocText
class	DocRoot

Functions
DocRoot *	validatingParseDoc (const char *fileName, int startLine, Definition *context, MemberDef *md, const char *input, bool indexWords, bool isExample, const char *exampleName=0, bool singleLine=FALSE, bool linkFromIndex=FALSE)
DocText *	validatingParseText (const char *input)
void	docFindSections (const char *input, Definition *d, MemberGroup *m, const char *fileName)

Function Documentation

void docFindSections	(	const char *	input,
		Definition *	d,
		MemberGroup *	m,
		const char *	fileName
	)

Searches for section and anchor commands in the input

Definition at line 7475 of file docparser.cpp.

References doctokenizerYYFindSections().

Referenced by PageDef::findSectionsInDocumentation(), MemberGroup::findSectionsInDocumentation(), GroupDef::findSectionsInDocumentation(), NamespaceDef::findSectionsInDocumentation(), FileDef::findSectionsInDocumentation(), ClassDef::findSectionsInDocumentation(), and MemberDef::findSectionsInDocumentation().

{
  doctokenizerYYFindSections(input,d,mg,fileName);
}

DocRoot* validatingParseDoc	(	const char *	fileName,
		int	startLine,
		Definition *	context,
		MemberDef *	md,
		const char *	input,
		bool	indexWords,
		bool	isExample,
		const char *	exampleName = 0,
		bool	singleLine = FALSE,
		bool	linkFromIndex = FALSE
	)

Main entry point for the documentation parser.

Parameters

fileName	File in which the documentation block is found (or the name of the example file in case isExample is TRUE).
startLine	Line at which the documentation block is found.
context	Class or namespace to which this block belongs.
md	Member definition to which the documentation belongs. Can be 0.
input	String representation of the documentation block.
indexWords	Indicates whether or not words should be put in the search index.
isExample	TRUE if the documentation belongs to an example.
exampleName	Base name of the example file (0 if isExample is FALSE).
singleLine	Output should be presented on a single line, so without starting a new paragraph at the end.
linkFromIndex	TRUE if the documentation is generated from an index page. In this case context is not used to determine the relative path when making a link.

Returns

Root node of the abstract syntax tree. Ownership of the pointer is handed over to the caller.

Definition at line 7220 of file docparser.cpp.

References DocRoot::accept(), MemberDef::anchor(), Definition::anchor(), checkUndocumentedParams(), ClassDef::compoundTypeString(), DefinitionIntf::definitionType(), detectNoDocumentedParams(), docParserPopContext(), docParserPushContext(), doctokenizerYYinit(), doctokenizerYYlineno, g_context, g_exampleName, g_fileName, g_hasParamCommand, g_hasReturnCommand, g_includeFileLength, g_includeFileOffset, g_includeFileText, g_initialStyleStack, g_inSeeBlock, g_insideHtmlLink, g_isExample, g_nodeStack, g_paramsFound, g_relPath, g_searchUrl, g_styleStack, g_xmlComment, Definition::getLanguage(), getLanguageSpecificSeparator(), MemberDef::getOutputFileBase(), Definition::getOutputFileBase(), Doxygen::globalScope, GroupDef::groupTitle(), Debug::isFlagSet(), Definition::name(), DocRoot::parse(), Debug::PrintTree, processCopyDoc(), MemberDef::qualifiedName(), Definition::qualifiedName(), relativePathToRoot(), Doxygen::searchIndex, SearchIndexIntf::setCurrentDoc(), SrcLangExt_CSharp, SrcLangExt_Fortran, SrcLangExt_Java, substitute(), theTranslator, PageDef::title(), Translator::trGroup(), Translator::trMember(), Translator::trModule(), Translator::trNamespace(), Translator::trPackage(), Translator::trPage(), Translator::trSubprogram(), DefinitionIntf::TypeClass, DefinitionIntf::TypeGroup, DefinitionIntf::TypeNamespace, and DefinitionIntf::TypePage.

Referenced by addPerlModDocBlock(), generateBriefDoc(), OutputList::generateDoc(), parseCommentAsText(), parseDoc(), DirDef::writeBriefDescription(), NamespaceDef::writeBriefDescription(), GroupDef::writeBriefDescription(), FileDef::writeBriefDescription(), MemberDef::writeDeclaration(), ClassDef::writeDeclarationLink(), writeDocbookDocBlock(), MemberList::writePlainDeclarations(), and writeXMLDocBlock().

{
  //printf("validatingParseDoc(%s,%s)=[%s]\n",ctx?ctx->name().data():"<none>",
  //                                     md?md->name().data():"<none>",
  //                                     input);
  //printf("========== validating %s at line %d\n",fileName,startLine);
  //printf("---------------- input --------------------\n%s\n----------- end input -------------------\n",input);
  //g_token = new TokenInfo;

  // store parser state so we can re-enter this function if needed
  //bool fortranOpt = Config_getBool(OPTIMIZE_FOR_FORTRAN);
  docParserPushContext();

  if (ctx && ctx!=Doxygen::globalScope &&
      (ctx->definitionType()==Definition::TypeClass || 
       ctx->definitionType()==Definition::TypeNamespace
      ) 
     ) 
  {
    g_context = ctx->name();
  }
  else if (ctx && ctx->definitionType()==Definition::TypePage)
  {
    Definition *scope = ((PageDef*)ctx)->getPageScope();
    if (scope && scope!=Doxygen::globalScope) g_context = scope->name();
  }
  else if (ctx && ctx->definitionType()==Definition::TypeGroup)
  {
    Definition *scope = ((GroupDef*)ctx)->getGroupScope();
    if (scope && scope!=Doxygen::globalScope) g_context = scope->name();
  }
  else
  {
    g_context = "";
  }
  g_scope = ctx;

  if (indexWords && Doxygen::searchIndex)
  {
    if (md)
    {
      g_searchUrl=md->getOutputFileBase();
      Doxygen::searchIndex->setCurrentDoc(md,md->anchor(),FALSE);
    }
    else if (ctx)
    {
      g_searchUrl=ctx->getOutputFileBase();
      Doxygen::searchIndex->setCurrentDoc(ctx,ctx->anchor(),FALSE);
    }
  }
#if 0
  if (indexWords && md && Doxygen::searchIndex)
  {
    g_searchUrl=md->getOutputFileBase();
    Doxygen::searchIndex->setCurrentDoc(
        (md->getLanguage()==SrcLangExt_Fortran ? 
         theTranslator->trSubprogram(TRUE,TRUE):
         theTranslator->trMember(TRUE,TRUE))+" "+md->qualifiedName(),
        g_searchUrl,
        md->anchor());
  }
  else if (indexWords && ctx && Doxygen::searchIndex)
  {
    g_searchUrl=ctx->getOutputFileBase();
    QCString name = ctx->qualifiedName();

    SrcLangExt lang = ctx->getLanguage();
    QCString sep = getLanguageSpecificSeparator(lang);
    if (sep!="::")
    {
      name = substitute(name,"::",sep);
    }

    switch (ctx->definitionType())
    {
      case Definition::TypePage:
        {
          PageDef *pd = (PageDef *)ctx;
          if (!pd->title().isEmpty())
          {
            name = theTranslator->trPage(TRUE,TRUE)+" "+pd->title();
          }
          else
          {
            name = theTranslator->trPage(TRUE,TRUE)+" "+pd->name();
          }
        }
        break;
      case Definition::TypeClass:
        {
          ClassDef *cd = (ClassDef *)ctx;
          name.prepend(cd->compoundTypeString()+" ");
        }
        break;
      case Definition::TypeNamespace:
        {
          if (lang==SrcLangExt_Java || lang==SrcLangExt_CSharp)
          {
            name = theTranslator->trPackage(name);
          }
          else if (lang==SrcLangExt_Fortran)
          {
            name.prepend(theTranslator->trModule(TRUE,TRUE)+" ");
          }
          else
          {
            name.prepend(theTranslator->trNamespace(TRUE,TRUE)+" ");
          }
        }
        break;
      case Definition::TypeGroup:
        {
          GroupDef *gd = (GroupDef *)ctx;
          if (gd->groupTitle())
          {
            name = theTranslator->trGroup(TRUE,TRUE)+" "+gd->groupTitle();
          }
          else
          {
            name.prepend(theTranslator->trGroup(TRUE,TRUE)+" ");
          }
        }
        break;
      default:
        break;
    }
    Doxygen::searchIndex->setCurrentDoc(name,g_searchUrl);
  }
#endif
  else
  {
    g_searchUrl="";
  }

  g_fileName = fileName;
  g_relPath = (!linkFromIndex && ctx) ? 
               QCString(relativePathToRoot(ctx->getOutputFileBase())) : 
               QCString("");
  //printf("ctx->name=%s relPath=%s\n",ctx->name().data(),g_relPath.data());
  g_memberDef = md;
  g_nodeStack.clear();
  g_styleStack.clear();
  g_initialStyleStack.clear();
  g_inSeeBlock = FALSE;
  g_xmlComment = FALSE;
  g_insideHtmlLink = FALSE;
  g_includeFileText = "";
  g_includeFileOffset = 0;
  g_includeFileLength = 0;
  g_isExample = isExample;
  g_exampleName = exampleName;
  g_hasParamCommand = FALSE;
  g_hasReturnCommand = FALSE;
  g_paramsFound.setAutoDelete(FALSE);
  g_paramsFound.clear();
  g_sectionDict = 0; //sections;
  
  //printf("Starting comment block at %s:%d\n",g_fileName.data(),startLine);
  doctokenizerYYlineno=startLine;
  uint inpLen=qstrlen(input);
  QCString inpStr = processCopyDoc(input,inpLen);
  if (inpStr.isEmpty() || inpStr.at(inpStr.length()-1)!='\n')
  {
    inpStr+='\n';
  }
  //printf("processCopyDoc(in='%s' out='%s')\n",input,inpStr.data());
  doctokenizerYYinit(inpStr,g_fileName);

  // build abstract syntax tree
  DocRoot *root = new DocRoot(md!=0,singleLine);
  root->parse();


  if (Debug::isFlagSet(Debug::PrintTree))
  {
    // pretty print the result
    PrintDocVisitor *v = new PrintDocVisitor;
    root->accept(v);
    delete v;
  }

  checkUndocumentedParams();
  detectNoDocumentedParams();

  // TODO: These should be called at the end of the program.
  //doctokenizerYYcleanup();
  //Mappers::cmdMapper->freeInstance();
  //Mappers::htmlTagMapper->freeInstance();

  // restore original parser state
  docParserPopContext();

  //printf(">>>>>> end validatingParseDoc(%s,%s)\n",ctx?ctx->name().data():"<none>",
  //                                     md?md->name().data():"<none>");
  
  return root;
}

DocText* validatingParseText

(

const char *

input

)

Main entry point for parsing simple text fragments. These fragments are limited to words, whitespace and symbols.

Definition at line 7422 of file docparser.cpp.

References DocText::accept(), docParserPopContext(), docParserPushContext(), doctokenizerYYinit(), doctokenizerYYlineno, g_context, g_exampleName, g_fileName, g_hasParamCommand, g_hasReturnCommand, g_includeFileLength, g_includeFileOffset, g_includeFileText, g_initialStyleStack, g_inSeeBlock, g_insideHtmlLink, g_isExample, g_nodeStack, g_paramsFound, g_relPath, g_searchUrl, g_styleStack, g_xmlComment, Debug::isFlagSet(), DocText::parse(), and Debug::PrintTree.

Referenced by RTFGenerator::endIndexSection(), and OutputList::parseText().

{
  // store parser state so we can re-enter this function if needed
  docParserPushContext();

  //printf("------------ input ---------\n%s\n"
  //       "------------ end input -----\n",input);
  //g_token = new TokenInfo;
  g_context = "";
  g_fileName = "<parseText>";
  g_relPath = "";
  g_memberDef = 0;
  g_nodeStack.clear();
  g_styleStack.clear();
  g_initialStyleStack.clear();
  g_inSeeBlock = FALSE;
  g_xmlComment = FALSE;
  g_insideHtmlLink = FALSE;
  g_includeFileText = "";
  g_includeFileOffset = 0;
  g_includeFileLength = 0;
  g_isExample = FALSE;
  g_exampleName = "";
  g_hasParamCommand = FALSE;
  g_hasReturnCommand = FALSE;
  g_paramsFound.setAutoDelete(FALSE);
  g_paramsFound.clear();
  g_searchUrl="";

  DocText *txt = new DocText;

  if (input)
  {
    doctokenizerYYlineno=1;
    doctokenizerYYinit(input,g_fileName);

    // build abstract syntax tree
    txt->parse();

    if (Debug::isFlagSet(Debug::PrintTree))
    {
      // pretty print the result
      PrintDocVisitor *v = new PrintDocVisitor;
      txt->accept(v);
      delete v;
    }
  }

  // restore original parser state
  docParserPopContext();
  return txt;
}