docparser.cpp File Reference

#include <stdio.h>
#include <stdlib.h>
#include <cassert>
#include <ctype.h>
#include "classlist.h"
#include "cmdmapper.h"
#include "config.h"
#include "debug.h"
#include "dir.h"
#include "docparser.h"
#include "docparser_p.h"
#include "doxygen.h"
#include "filedef.h"
#include "fileinfo.h"
#include "groupdef.h"
#include "namespacedef.h"
#include "message.h"
#include "pagedef.h"
#include "portable.h"
#include "printdocvisitor.h"
#include "util.h"
#include "indexlist.h"
#include "trace.h"
#include "stringutil.h"

Include dependency graph for docparser.cpp:

Go to the source code of this file.

Macros
#define	AUTO_TRACE(...)
#define	AUTO_TRACE_ADD(...)
#define	AUTO_TRACE_EXIT(...)
#define	CHECK_FOR_COMMAND(str, action)

Functions
IDocParserPtr	createDocParser ()
	factory function to create a parser
static QCString	extractCopyDocId (const char *data, size_t &j, size_t len)
static size_t	isCopyBriefOrDetailsCmd (const char *data, size_t i, size_t len, bool &brief)
static size_t	isVerbatimSection (const char *data, size_t i, size_t len, QCString &endMarker)
static size_t	skipToEndMarker (const char *data, size_t i, size_t len, const QCString &endMarker)
IDocNodeASTPtr	validatingParseDoc (IDocParser &parserIntf, const QCString &fileName, int startLine, const Definition *ctx, const MemberDef *md, const QCString &input, bool indexWords, bool isExample, const QCString &exampleName, bool singleLine, bool linkFromIndex, bool markdownSupport)
IDocNodeASTPtr	validatingParseText (IDocParser &parserIntf, const QCString &input)
IDocNodeASTPtr	createRef (IDocParser &parserIntf, const QCString &target, const QCString &context, const QCString &srcFile, int srcLine)
void	docFindSections (const QCString &input, const Definition *d, const QCString &fileName)

Macro Definition Documentation

AUTO_TRACE

#define AUTO_TRACE

(

...

)

Value:

(void)0

Definition at line 47 of file docparser.cpp.

AUTO_TRACE_ADD

#define AUTO_TRACE_ADD

(

...

)

Value:

(void)0

Definition at line 48 of file docparser.cpp.

AUTO_TRACE_EXIT

#define AUTO_TRACE_EXIT

(

...

)

Value:

(void)0

Definition at line 49 of file docparser.cpp.

CHECK_FOR_COMMAND

#define CHECK_FOR_COMMAND	(		str,
			action )

Value:

   do if ((i+sizeof(str)<len) && literal_at(data+i+1,str)) \
   { j=i+sizeof(str); action; } while(0)

Definition at line 1749 of file docparser.cpp.

#define CHECK_FOR_COMMAND(str,action) \
   do if ((i+sizeof(str)<len) && literal_at(data+i+1,str)) \
   { j=i+sizeof(str); action; } while(0)

Referenced by isCopyBriefOrDetailsCmd(), and isVerbatimSection().

Function Documentation

createDocParser()

IDocParserPtr createDocParser

(

)

factory function to create a parser

Definition at line 55 of file docparser.cpp.

{
  return std::make_unique<DocParser>();
}

Referenced by addPerlModDocBlock(), convertMapFile(), RTFGenerator::endIndexSection(), generateBriefDoc(), OutputList::generateDoc(), generateHtmlOutput(), getSQLDocBlock(), parseCommentAsText(), OutputList::parseText(), replaceRef(), LayoutNavEntry::url(), ConceptDefImpl::writeBriefDescription(), DirDefImpl::writeBriefDescription(), FileDefImpl::writeBriefDescription(), GroupDefImpl::writeBriefDescription(), ModuleDefImpl::writeBriefDescription(), NamespaceDefImpl::writeBriefDescription(), MemberDefImpl::writeDeclaration(), ClassDefImpl::writeDeclarationLink(), ConceptDefImpl::writeDeclarationLink(), ModuleDefImpl::writeDeclarationLink(), MemberList::writePlainDeclarations(), and writeXMLDocBlock().

createRef()

IDocNodeASTPtr createRef	(	IDocParser &	parserIntf,
		const QCString &	target,
		const QCString &	context,
		const QCString &	srcFile,
		int	srcLine )

Definition at line 2106 of file docparser.cpp.

{
  DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);
  assert(parser!=nullptr);
  if (parser==nullptr) return nullptr;
  if (!srcFile.isEmpty())
  {
    parser->context.fileName = srcFile;
    parser->tokenizer.setLineNr(srcLine);
  }
  return std::make_unique<DocNodeAST>(DocRef(parser,nullptr,target,context));
}

References DocParser::context, DocParserContext::fileName, QCString::isEmpty(), DocTokenizer::setLineNr(), and DocParser::tokenizer.

Referenced by convertMapFile(), replaceRef(), and LayoutNavEntry::url().

docFindSections()

void docFindSections	(	const QCString &	input,
		const Definition *	d,
		const QCString &	fileName )

Searches for section and anchor commands in the input Sections found will be added to the SectionManager.

Definition at line 2119 of file docparser.cpp.

{
  DocParser parser;
  parser.tokenizer.findSections(input,d,fileName);
}

References DocTokenizer::findSections(), and DocParser::tokenizer.

Referenced by ClassDefImpl::findSectionsInDocumentation(), ConceptDefImpl::findSectionsInDocumentation(), FileDefImpl::findSectionsInDocumentation(), GroupDefImpl::findSectionsInDocumentation(), MemberDefImpl::findSectionsInDocumentation(), MemberGroup::findSectionsInDocumentation(), ModuleDefImpl::findSectionsInDocumentation(), NamespaceDefImpl::findSectionsInDocumentation(), and PageDefImpl::findSectionsInDocumentation().

extractCopyDocId()

QCString extractCopyDocId ( const char * data, size_t & j, size_t len )

static

Definition at line 1676 of file docparser.cpp.

{
  size_t s=j;
  int round=0;
  bool insideDQuote=FALSE;
  bool insideSQuote=FALSE;
  bool found=FALSE;
  while (j<len && !found)
  {
    if (!insideSQuote && !insideDQuote)
    {
      switch (data[j])
      {
        case '(': round++; break;
        case ')': round--; break;
        case '"': insideDQuote=TRUE; break;
        case '\'': insideSQuote=TRUE; break;
        case '\\': // fall through, begin of command
        case '@':  // fall through, begin of command
        case '\t': // fall through
        case '\n':
          found=(round==0);
          break;
        case ' ':  // allow spaces in cast operator (see issue #11169)
          found=(round==0) && (j<8 || !literal_at(data+j-8,"operator"));
          break;
      }
    }
    else if (insideSQuote) // look for single quote end
    {
      if (data[j]=='\'' && (j==0 || data[j]!='\\'))
      {
        insideSQuote=FALSE;
      }
    }
    else if (insideDQuote) // look for double quote end
    {
      if (data[j]=='"' && (j==0 || data[j]!='\\'))
      {
        insideDQuote=FALSE;
      }
    }
    if (!found) j++;
  }
 
  // include const and volatile
  if (literal_at(data+j," const"))
  {
    j+=6;
  }
  else if (literal_at(data+j," volatile"))
  {
    j+=9;
  }
 
  // allow '&' or '&&' or ' &' or ' &&' at the end
  size_t k=j;
  while (k<len && data[k]==' ') k++;
  if      (k<len-1 && data[k]=='&' && data[k+1]=='&') j=k+2;
  else if (k<len   && data[k]=='&'                  ) j=k+1;
 
  // do not include punctuation added by Definition::_setBriefDescription()
  size_t e=j;
  if (j>0 && data[j-1]=='.') { e--; }
  QCString id(data+s,e-s);
  //printf("extractCopyDocId='%s' input='%s'\n",qPrint(id),&data[s]);
  return id;
}

References FALSE, found, literal_at(), and TRUE.

Referenced by DocParser::processCopyDoc().

isCopyBriefOrDetailsCmd()

size_t isCopyBriefOrDetailsCmd ( const char * data, size_t i, size_t len, bool & brief )

static

Definition at line 1753 of file docparser.cpp.

{
  size_t j=0;
  if (i==0 || (data[i-1]!='@' && data[i-1]!='\\')) // not an escaped command
  {
    CHECK_FOR_COMMAND("copybrief",brief=TRUE);    // @copybrief or \copybrief
    CHECK_FOR_COMMAND("copydetails",brief=FALSE); // @copydetails or \copydetails
  }
  return j;
}

References CHECK_FOR_COMMAND, FALSE, and TRUE.

Referenced by DocParser::processCopyDoc().

isVerbatimSection()

size_t isVerbatimSection ( const char * data, size_t i, size_t len, QCString & endMarker )

static

Definition at line 1764 of file docparser.cpp.

{
  size_t j=0;
  if (i==0 || (data[i-1]!='@' && data[i-1]!='\\')) // not an escaped command
  {
    CHECK_FOR_COMMAND("dot",endMarker="enddot");
    CHECK_FOR_COMMAND("icode",endMarker="endicode");
    CHECK_FOR_COMMAND("code",endMarker="endcode");
    CHECK_FOR_COMMAND("msc",endMarker="endmsc");
    CHECK_FOR_COMMAND("iverbatim",endMarker="endiverbatim");
    CHECK_FOR_COMMAND("verbatim",endMarker="endverbatim");
    CHECK_FOR_COMMAND("iliteral",endMarker="endiliteral");
    CHECK_FOR_COMMAND("latexonly",endMarker="endlatexonly");
    CHECK_FOR_COMMAND("htmlonly",endMarker="endhtmlonly");
    CHECK_FOR_COMMAND("xmlonly",endMarker="endxmlonly");
    CHECK_FOR_COMMAND("rtfonly",endMarker="endrtfonly");
    CHECK_FOR_COMMAND("manonly",endMarker="endmanonly");
    CHECK_FOR_COMMAND("docbookonly",endMarker="enddocbookonly");
    CHECK_FOR_COMMAND("startuml",endMarker="enduml");
  }
  //printf("isVerbatimSection(%s)=%d)\n",qPrint(QCString(&data[i]).left(10)),j);
  return j;
}

References CHECK_FOR_COMMAND.

Referenced by DocParser::processCopyDoc().

skipToEndMarker()

size_t skipToEndMarker ( const char * data, size_t i, size_t len, const QCString & endMarker )

static

Definition at line 1788 of file docparser.cpp.

{
  while (i<len)
  {
    if ((data[i]=='@' || data[i]=='\\') &&  // start of command character
        (i==0 || (data[i-1]!='@' && data[i-1]!='\\'))) // that is not escaped
    {
      if (i+endMarker.length()+1<=len && qstrncmp(data+i+1,endMarker.data(),endMarker.length())==0)
      {
        return i+endMarker.length()+1;
      }
    }
    i++;
  }
  // oops no endmarker found...
  return i<len ? i+1 : len;
}

References QCString::data(), QCString::length(), and qstrncmp().

Referenced by DocParser::processCopyDoc().

validatingParseDoc()

IDocNodeASTPtr validatingParseDoc	(	IDocParser &	parserIntf,
		const QCString &	fileName,
		int	startLine,
		const Definition *	ctx,
		const MemberDef *	md,
		const QCString &	input,
		bool	indexWords,
		bool	isExample,
		const QCString &	exampleName,
		bool	singleLine,
		bool	linkFromIndex,
		bool	markdownSupport )

Main entry point for the comment block parser.

Parameters

parserIntf	The parser object created via createDocParser()
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.
ctx	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.
markdownSupport	TRUE if the input needs to take markdown markup into account.

Returns

An object representing the abstract syntax tree. Ownership of the pointer is handed over to the caller.

Definition at line 1920 of file docparser.cpp.

{
  DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);
  assert(parser!=nullptr);
  if (parser==nullptr) return nullptr;
  //printf("validatingParseDoc(%s,%s)=[%s]\n",ctx?qPrint(ctx->name()):"<none>",
  //                                     md?qPrint(md->name()):"<none>",
  //                                     qPrint(input));
  //printf("========== validating %s at line %d\n",qPrint(fileName),startLine);
  //printf("---------------- input --------------------\n%s\n----------- end input -------------------\n",qPrint(input));
 
  // set initial token
  parser->context.token = parser->tokenizer.resetToken();
 
  if (ctx && ctx!=Doxygen::globalScope &&
      (ctx->definitionType()==Definition::TypeClass ||
       ctx->definitionType()==Definition::TypeNamespace
      )
     )
  {
    parser->context.context = substitute(ctx->qualifiedName(),getLanguageSpecificSeparator(ctx->getLanguage(),true),"::");
  }
  else if (ctx && ctx->definitionType()==Definition::TypePage)
  {
    const Definition *scope = (toPageDef(ctx))->getPageScope();
    if (scope && scope!=Doxygen::globalScope)
    {
      parser->context.context = substitute(scope->name(),getLanguageSpecificSeparator(scope->getLanguage(),true),"::");
    }
  }
  else if (ctx && ctx->definitionType()==Definition::TypeGroup)
  {
    const Definition *scope = (toGroupDef(ctx))->getGroupScope();
    if (scope && scope!=Doxygen::globalScope)
    {
      parser->context.context = substitute(scope->name(),getLanguageSpecificSeparator(scope->getLanguage(),true),"::");
    }
  }
  else
  {
    parser->context.context = "";
  }
  parser->context.scope = ctx;
  parser->context.lang = getLanguageFromFileName(fileName);
 
  if (indexWords && Doxygen::searchIndex.enabled())
  {
    if (md)
    {
      parser->context.searchUrl=md->getOutputFileBase();
      Doxygen::searchIndex.setCurrentDoc(md,md->anchor(),false);
    }
    else if (ctx)
    {
      parser->context.searchUrl=ctx->getOutputFileBase();
      Doxygen::searchIndex.setCurrentDoc(ctx,ctx->anchor(),false);
    }
  }
  else
  {
    parser->context.searchUrl="";
  }
 
  parser->context.fileName = fileName;
  parser->context.relPath = (!linkFromIndex && ctx) ?
               QCString(relativePathToRoot(ctx->getOutputFileBase())) :
               QCString("");
  //printf("ctx->name=%s relPath=%s\n",qPrint(ctx->name()),qPrint(parser->context.relPath));
  parser->context.memberDef = md;
  while (!parser->context.nodeStack.empty()) parser->context.nodeStack.pop();
  while (!parser->context.styleStack.empty()) parser->context.styleStack.pop();
  while (!parser->context.initialStyleStack.empty()) parser->context.initialStyleStack.pop();
  parser->context.inSeeBlock = FALSE;
  parser->context.xmlComment = FALSE;
  parser->context.insideHtmlLink = FALSE;
  parser->context.includeFileText = "";
  parser->context.includeFileOffset = 0;
  parser->context.includeFileLength = 0;
  parser->context.isExample = isExample;
  parser->context.exampleName = exampleName;
  parser->context.hasParamCommand = FALSE;
  parser->context.hasReturnCommand = FALSE;
  parser->context.retvalsFound.clear();
  parser->context.paramsFound.clear();
  parser->context.markdownSupport = markdownSupport;
 
  //printf("Starting comment block at %s:%d\n",qPrint(parser->context.fileName),startLine);
  parser->tokenizer.setLineNr(startLine);
  size_t ioLen = input.length();
  QCString inpStr = parser->processCopyDoc(input.data(),ioLen);
  if (inpStr.isEmpty() || inpStr.at(inpStr.length()-1)!='\n')
  {
    inpStr+='\n';
  }
  //printf("processCopyDoc(in='%s' out='%s')\n",input,qPrint(inpStr));
  parser->tokenizer.init(inpStr.data(),parser->context.fileName,
                         parser->context.markdownSupport,parser->context.insideHtmlLink);
 
  // build abstract syntax tree
  auto ast = std::make_unique<DocNodeAST>(DocRoot(parser,md!=nullptr,singleLine));
  std::get<DocRoot>(ast->root).parse();
 
  if (Debug::isFlagSet(Debug::PrintTree))
  {
    // pretty print the result
    std::visit(PrintDocVisitor{},ast->root);
  }
 
  if (md && md->isFunction())
  {
    parser->checkUnOrMultipleDocumentedParams();
  }
  if (parser->context.memberDef) parser->context.memberDef->detectUndocumentedParams(parser->context.hasParamCommand,parser->context.hasReturnCommand);
 
  // reset token
  parser->tokenizer.resetToken();
 
  //printf(">>>>>> end validatingParseDoc(%s,%s)\n",ctx?qPrint(ctx->name()):"<none>",
  //                                     md?qPrint(md->name()):"<none>");
 
  return ast;
}

References Definition::anchor(), QCString::at(), DocParser::checkUnOrMultipleDocumentedParams(), DocParser::context, DocParserContext::context, QCString::data(), Definition::definitionType(), MemberDef::detectUndocumentedParams(), DocParserContext::exampleName, FALSE, DocParserContext::fileName, Definition::getLanguage(), getLanguageFromFileName(), getLanguageSpecificSeparator(), Definition::getOutputFileBase(), Doxygen::globalScope, DocParserContext::hasParamCommand, DocParserContext::hasReturnCommand, DocParserContext::includeFileLength, DocParserContext::includeFileOffset, DocParserContext::includeFileText, DocTokenizer::init(), DocParserContext::initialStyleStack, DocParserContext::inSeeBlock, DocParserContext::insideHtmlLink, QCString::isEmpty(), DocParserContext::isExample, Debug::isFlagSet(), MemberDef::isFunction(), DocParserContext::lang, QCString::length(), DocParserContext::markdownSupport, DocParserContext::memberDef, Definition::name(), DocParserContext::nodeStack, DocParserContext::paramsFound, Debug::PrintTree, DocParser::processCopyDoc(), Definition::qualifiedName(), relativePathToRoot(), DocParserContext::relPath, DocTokenizer::resetToken(), DocParserContext::retvalsFound, DocParserContext::scope, Doxygen::searchIndex, DocParserContext::searchUrl, DocTokenizer::setLineNr(), DocParserContext::styleStack, substitute(), toGroupDef(), DocParserContext::token, DocParser::tokenizer, toPageDef(), Definition::TypeClass, Definition::TypeGroup, Definition::TypeNamespace, Definition::TypePage, and DocParserContext::xmlComment.

Referenced by addPerlModDocBlock(), generateBriefDoc(), OutputList::generateDoc(), generateHtmlOutput(), getSQLDocBlock(), parseCommentAsText(), ConceptDefImpl::writeBriefDescription(), DirDefImpl::writeBriefDescription(), FileDefImpl::writeBriefDescription(), GroupDefImpl::writeBriefDescription(), ModuleDefImpl::writeBriefDescription(), NamespaceDefImpl::writeBriefDescription(), MemberDefImpl::writeDeclaration(), ClassDefImpl::writeDeclarationLink(), ConceptDefImpl::writeDeclarationLink(), ModuleDefImpl::writeDeclarationLink(), MemberList::writePlainDeclarations(), and writeXMLDocBlock().

validatingParseText()

IDocNodeASTPtr validatingParseText	(	IDocParser &	parser,
		const QCString &	input )

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

Definition at line 2049 of file docparser.cpp.

{
  DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);
  assert(parser!=nullptr);
  if (parser==nullptr) return nullptr;
 
  // set initial token
  parser->context.token = parser->tokenizer.resetToken();
 
  //printf("------------ input ---------\n%s\n"
  //       "------------ end input -----\n",input);
  //parser->context.token = new TokenInfo;
  parser->context.context = "";
  parser->context.fileName = "<parseText>";
  parser->context.relPath = "";
  parser->context.memberDef = nullptr;
  while (!parser->context.nodeStack.empty()) parser->context.nodeStack.pop();
  while (!parser->context.styleStack.empty()) parser->context.styleStack.pop();
  while (!parser->context.initialStyleStack.empty()) parser->context.initialStyleStack.pop();
  parser->context.inSeeBlock = FALSE;
  parser->context.xmlComment = FALSE;
  parser->context.insideHtmlLink = FALSE;
  parser->context.includeFileText = "";
  parser->context.includeFileOffset = 0;
  parser->context.includeFileLength = 0;
  parser->context.isExample = FALSE;
  parser->context.exampleName = "";
  parser->context.hasParamCommand = FALSE;
  parser->context.hasReturnCommand = FALSE;
  parser->context.retvalsFound.clear();
  parser->context.paramsFound.clear();
  parser->context.searchUrl="";
  parser->context.lang = SrcLangExt::Unknown;
  parser->context.markdownSupport = Config_getBool(MARKDOWN_SUPPORT);
 
 
  auto ast = std::make_unique<DocNodeAST>(DocText(parser));
 
  if (!input.isEmpty())
  {
    parser->tokenizer.setLineNr(1);
    parser->tokenizer.init(input.data(),parser->context.fileName,
                           parser->context.markdownSupport,parser->context.insideHtmlLink);
 
    // build abstract syntax tree
    std::get<DocText>(ast->root).parse();
 
    if (Debug::isFlagSet(Debug::PrintTree))
    {
      // pretty print the result
      std::visit(PrintDocVisitor{},ast->root);
    }
  }
 
  return ast;
}

References Config_getBool, DocParser::context, DocParserContext::context, QCString::data(), DocParserContext::exampleName, FALSE, DocParserContext::fileName, DocParserContext::hasParamCommand, DocParserContext::hasReturnCommand, DocParserContext::includeFileLength, DocParserContext::includeFileOffset, DocParserContext::includeFileText, DocTokenizer::init(), DocParserContext::initialStyleStack, DocParserContext::inSeeBlock, DocParserContext::insideHtmlLink, QCString::isEmpty(), DocParserContext::isExample, Debug::isFlagSet(), DocParserContext::lang, DocParserContext::markdownSupport, DocParserContext::memberDef, DocParserContext::nodeStack, DocParserContext::paramsFound, Debug::PrintTree, DocParserContext::relPath, DocTokenizer::resetToken(), DocParserContext::retvalsFound, DocParserContext::searchUrl, DocTokenizer::setLineNr(), DocParserContext::styleStack, DocParserContext::token, DocParser::tokenizer, and DocParserContext::xmlComment.

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