docparser.h File Reference

#include <stdio.h>
#include <memory>
#include "qcstring.h"
#include "growvector.h"
#include "construct.h"
#include "types.h"
#include "docoptions.h"

Include dependency graph for docparser.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	IDocParser
	opaque parser interface More...
class	IDocNodeAST
	opaque representation of the abstract syntax tree (AST) More...

Typedefs
using	IDocParserPtr = std::unique_ptr<IDocParser>
	pointer to parser interface
using	IDocNodeASTPtr = std::unique_ptr<IDocNodeAST>

Functions
IDocParserPtr	createDocParser ()
	factory function to create a parser
IDocNodeASTPtr	validatingParseDoc (IDocParser &parserIntf, const QCString &fileName, int startLine, const Definition *ctx, const MemberDef *md, const QCString &input, const DocOptions &options)
IDocNodeASTPtr	validatingParseText (IDocParser &parser, const QCString &input)
IDocNodeASTPtr	validatingParseTitle (IDocParser &parserIntf, const QCString &fileName, int lineNr, const QCString &input)
IDocNodeASTPtr	createRef (IDocParser &parser, const QCString &target, const QCString &context, const QCString &srcFile="", int srcLine=-1)
void	docFindSections (const QCString &input, const Definition *d, const QCString &fileName)

Typedef Documentation

IDocNodeASTPtr

using IDocNodeASTPtr = std::unique_ptr<IDocNodeAST>

Definition at line 57 of file docparser.h.

IDocParserPtr

using IDocParserPtr = std::unique_ptr<IDocParser>

pointer to parser interface

Definition at line 41 of file docparser.h.

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(), parseCommentAsHtml(), 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 &	parser,
		const QCString &	target,
		const QCString &	context,
		const QCString &	srcFile = "",
		int	srcLine = -1 )

Definition at line 2441 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.setFileName(srcFile);
    parser->tokenizer.setLineNr(srcLine);
  }
  return std::make_unique<DocNodeAST>(DocRef(parser,nullptr,target,context));
}

References DocParser::context, DocParserContext::fileName, QCString::isEmpty(), DocTokenizer::setFileName(), 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 2455 of file docparser.cpp.

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

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

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

validatingParseDoc()

IDocNodeASTPtr validatingParseDoc	(	IDocParser &	parserIntf,
		const QCString &	fileName,
		int	startLine,
		const Definition *	ctx,
		const MemberDef *	md,
		const QCString &	input,
		const DocOptions &	options )

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.
options	Optional parameters.

Returns

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

Definition at line 2187 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 (options.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 = (!options.linkFromIndex() && ctx) ?
               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.inCodeStyle = FALSE;
  parser->context.xmlComment = FALSE;
  parser->context.insideHtmlLink = FALSE;
  parser->context.includeFileText = "";
  parser->context.includeFileOffset = 0;
  parser->context.includeFileLength = 0;
  parser->context.isExample = options.isExample();
  parser->context.exampleName = options.exampleName();
  parser->context.hasParamCommand = FALSE;
  parser->context.hasReturnCommand = FALSE;
  parser->context.retvalsFound.clear();
  parser->context.paramsFound.clear();
  parser->context.markdownSupport = options.markdownSupport();
  parser->context.autolinkSupport = options.autolinkSupport();
  if (md)
  {
    const ArgumentList &al=md->isDocsForDefinition() ? md->argumentList() : md->declArgumentList();
    parser->context.numParameters = static_cast<int>(al.size());
  }
  else
  {
    parser->context.numParameters = 0;
  }
  parser->context.paramPosition = 1;
 
  //printf("Starting comment block at %s:%d\n",qPrint(parser->context.fileName),startLine);
  parser->tokenizer.setFileName(fileName);
  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",qPrint(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,options.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(), MemberDef::argumentList(), QCString::at(), DocOptions::autolinkSupport(), DocParserContext::autolinkSupport, DocParser::checkUnOrMultipleDocumentedParams(), DocParser::context, DocParserContext::context, QCString::data(), MemberDef::declArgumentList(), Definition::definitionType(), MemberDef::detectUndocumentedParams(), DocOptions::exampleName(), DocParserContext::exampleName, FALSE, DocParserContext::fileName, Definition::getLanguage(), getLanguageFromFileName(), getLanguageSpecificSeparator(), Definition::getOutputFileBase(), Doxygen::globalScope, DocParserContext::hasParamCommand, DocParserContext::hasReturnCommand, DocParserContext::includeFileLength, DocParserContext::includeFileOffset, DocParserContext::includeFileText, DocParserContext::inCodeStyle, DocOptions::indexWords(), DocTokenizer::init(), DocParserContext::initialStyleStack, DocParserContext::inSeeBlock, DocParserContext::insideHtmlLink, MemberDef::isDocsForDefinition(), QCString::isEmpty(), DocOptions::isExample(), DocParserContext::isExample, Debug::isFlagSet(), MemberDef::isFunction(), DocParserContext::lang, QCString::length(), DocOptions::linkFromIndex(), DocOptions::markdownSupport(), DocParserContext::markdownSupport, DocParserContext::memberDef, Definition::name(), DocParserContext::nodeStack, DocParserContext::numParameters, DocParserContext::paramPosition, DocParserContext::paramsFound, Debug::PrintTree, DocParser::processCopyDoc(), Definition::qualifiedName(), relativePathToRoot(), DocParserContext::relPath, DocTokenizer::resetToken(), DocParserContext::retvalsFound, DocParserContext::scope, Doxygen::searchIndex, DocParserContext::searchUrl, DocTokenizer::setFileName(), DocTokenizer::setLineNr(), DocOptions::singleLine(), ArgumentList::size(), 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 2382 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.inCodeStyle = 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);
  parser->context.autolinkSupport = FALSE;
 
 
  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 DocParserContext::autolinkSupport, Config_getBool, DocParser::context, DocParserContext::context, QCString::data(), DocParserContext::exampleName, FALSE, DocParserContext::fileName, DocParserContext::hasParamCommand, DocParserContext::hasReturnCommand, DocParserContext::includeFileLength, DocParserContext::includeFileOffset, DocParserContext::includeFileText, DocParserContext::inCodeStyle, 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().

validatingParseTitle()

IDocNodeASTPtr validatingParseTitle	(	IDocParser &	parserIntf,
		const QCString &	fileName,
		int	lineNr,
		const QCString &	input )

Main entry point for parsing titles. These allow limited markup commands

Definition at line 2329 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.context = "";
  parser->context.fileName = fileName;
  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.inCodeStyle = 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);
  parser->context.autolinkSupport = false;
 
  auto ast = std::make_unique<DocNodeAST>(DocTitle(parser,nullptr));
 
  if (!input.isEmpty())
  {
    // build abstract syntax tree from title string
    std::get<DocTitle>(ast->root).parseFromString(nullptr,input);
 
    if (Debug::isFlagSet(Debug::PrintTree))
    {
      // pretty print the result
      std::visit(PrintDocVisitor{},ast->root);
    }
  }
 
  return ast;
}

References DocParserContext::autolinkSupport, Config_getBool, DocParser::context, DocParserContext::context, DocParserContext::exampleName, FALSE, DocParserContext::fileName, DocParserContext::hasParamCommand, DocParserContext::hasReturnCommand, DocParserContext::includeFileLength, DocParserContext::includeFileOffset, DocParserContext::includeFileText, DocParserContext::inCodeStyle, 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, DocParserContext::styleStack, DocParserContext::token, DocParser::tokenizer, and DocParserContext::xmlComment.

Referenced by parseCommentAsHtml().