The docparser.h File Reference

Included Headers

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

Classes Index

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

Typedefs Index

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

Functions Index

IDocParserPtr	createDocParser ()
	factory function to create a parser More...
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=Config_getBool(MARKDOWN_SUPPORT), bool autolinkSupport=Config_getBool(AUTOLINK_SUPPORT))
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)

Typedefs

IDocNodeASTPtr

using IDocNodeASTPtr = std::unique_ptr<IDocNodeAST>

Definition at line 57 of file docparser.h.

57using IDocNodeASTPtr = std::unique_ptr<IDocNodeAST>;

IDocParserPtr

using IDocParserPtr = std::unique_ptr<IDocParser>

pointer to parser interface

Definition at line 41 of file docparser.h.

41using IDocParserPtr = std::unique_ptr<IDocParser>;

Functions

createDocParser()

IDocParserPtr createDocParser ()

factory function to create a parser

Declaration at line 44 of file docparser.h, definition at line 55 of file docparser.cpp.

55IDocParserPtr createDocParser()

56{

57 return std::make_unique<DocParser>();

58}

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)

Declaration at line 102 of file docparser.h, definition at line 2163 of file docparser.cpp.

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

2164{

2165 DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);

2166 assert(parser!=nullptr);

2167 if (parser==nullptr) return nullptr;

2168 if (!srcFile.isEmpty())

2169 {

2170 parser->context.fileName = srcFile;

2171 parser->tokenizer.setLineNr(srcLine);

2172 }

2173 return std::make_unique<DocNodeAST>(DocRef(parser,nullptr,target,context));

2174}

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.

Declaration at line 109 of file docparser.h, definition at line 2176 of file docparser.cpp.

2176void docFindSections(const QCString &input,

2177 const Definition *d,

2178 const QCString &fileName)

2179{

2180 DocParser parser;

2181 parser.tokenizer.findSections(input,d,fileName);

2182}

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.

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=Config_getBool(MARKDOWN_SUPPORT), bool autolinkSupport=Config_getBool(AUTOLINK_SUPPORT))

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.
autolinkSupport	TRUE if the input need to perform auto linking of words

Returns

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

Declaration at line 83 of file docparser.h, definition at line 1922 of file docparser.cpp.

1922IDocNodeASTPtr validatingParseDoc(IDocParser &parserIntf,

1923 const QCString &fileName,int startLine,

1924 const Definition *ctx,const MemberDef *md,

1925 const QCString &input,bool indexWords,

1926 bool isExample, const QCString &exampleName,

1927 bool singleLine, bool linkFromIndex,

1928 bool markdownSupport,

1929 bool autolinkSupport)

1930{

1931 DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);

1932 assert(parser!=nullptr);

1933 if (parser==nullptr) return nullptr;

1934 //printf("validatingParseDoc(%s,%s)=[%s]\n",ctx?qPrint(ctx->name()):"<none>",

1935 // md?qPrint(md->name()):"<none>",

1936 // qPrint(input));

1937 //printf("========== validating %s at line %d\n",qPrint(fileName),startLine);

1938 //printf("---------------- input --------------------\n%s\n----------- end input -------------------\n",qPrint(input));

1939

1940 // set initial token

1941 parser->context.token = parser->tokenizer.resetToken();

1942

1943 if (ctx && ctx!=Doxygen::globalScope &&

1944 (ctx->definitionType()==Definition::TypeClass ||

1945 ctx->definitionType()==Definition::TypeNamespace

1946 )

1947 )

1948 {

1949 parser->context.context = substitute(ctx->qualifiedName(),getLanguageSpecificSeparator(ctx->getLanguage(),true),"::");

1950 }

1951 else if (ctx && ctx->definitionType()==Definition::TypePage)

1952 {

1953 const Definition *scope = (toPageDef(ctx))->getPageScope();

1954 if (scope && scope!=Doxygen::globalScope)

1955 {

1956 parser->context.context = substitute(scope->name(),getLanguageSpecificSeparator(scope->getLanguage(),true),"::");

1957 }

1958 }

1959 else if (ctx && ctx->definitionType()==Definition::TypeGroup)

1960 {

1961 const Definition *scope = (toGroupDef(ctx))->getGroupScope();

1962 if (scope && scope!=Doxygen::globalScope)

1963 {

1964 parser->context.context = substitute(scope->name(),getLanguageSpecificSeparator(scope->getLanguage(),true),"::");

1965 }

1966 }

1967 else

1968 {

1969 parser->context.context = "";

1970 }

1971 parser->context.scope = ctx;

1972 parser->context.lang = getLanguageFromFileName(fileName);

1973

1974 if (indexWords && Doxygen::searchIndex.enabled())

1975 {

1976 if (md)

1977 {

1978 parser->context.searchUrl=md->getOutputFileBase();

1979 Doxygen::searchIndex.setCurrentDoc(md,md->anchor(),false);

1980 }

1981 else if (ctx)

1982 {

1983 parser->context.searchUrl=ctx->getOutputFileBase();

1984 Doxygen::searchIndex.setCurrentDoc(ctx,ctx->anchor(),false);

1985 }

1986 }

1987 else

1988 {

1989 parser->context.searchUrl="";

1990 }

1991

1992 parser->context.fileName = fileName;

1993 parser->context.relPath = (!linkFromIndex && ctx) ?

1994 QCString(relativePathToRoot(ctx->getOutputFileBase())) :

1995 QCString("");

1996 //printf("ctx->name=%s relPath=%s\n",qPrint(ctx->name()),qPrint(parser->context.relPath));

1997 parser->context.memberDef = md;

1998 while (!parser->context.nodeStack.empty()) parser->context.nodeStack.pop();

1999 while (!parser->context.styleStack.empty()) parser->context.styleStack.pop();

2000 while (!parser->context.initialStyleStack.empty()) parser->context.initialStyleStack.pop();

2001 parser->context.inSeeBlock = FALSE;

2002 parser->context.xmlComment = FALSE;

2003 parser->context.insideHtmlLink = FALSE;

2004 parser->context.includeFileText = "";

2005 parser->context.includeFileOffset = 0;

2006 parser->context.includeFileLength = 0;

2007 parser->context.isExample = isExample;

2008 parser->context.exampleName = exampleName;

2009 parser->context.hasParamCommand = FALSE;

2010 parser->context.hasReturnCommand = FALSE;

2011 parser->context.retvalsFound.clear();

2012 parser->context.paramsFound.clear();

2013 parser->context.markdownSupport = markdownSupport;

2014 parser->context.autolinkSupport = autolinkSupport;

2015

2016 //printf("Starting comment block at %s:%d\n",qPrint(parser->context.fileName),startLine);

2017 parser->tokenizer.setLineNr(startLine);

2018 size_t ioLen = input.length();

2019 QCString inpStr = parser->processCopyDoc(input.data(),ioLen);

2020 if (inpStr.isEmpty() || inpStr.at(inpStr.length()-1)!='\n')

2021 {

2022 inpStr+='\n';

2023 }

2024 //printf("processCopyDoc(in='%s' out='%s')\n",input,qPrint(inpStr));

2025 parser->tokenizer.init(inpStr.data(),parser->context.fileName,

2026 parser->context.markdownSupport,parser->context.insideHtmlLink);

2027

2028 // build abstract syntax tree

2029 auto ast = std::make_unique<DocNodeAST>(DocRoot(parser,md!=nullptr,singleLine));

2030 std::get<DocRoot>(ast->root).parse();

2031

2032 if (Debug::isFlagSet(Debug::PrintTree))

2033 {

2034 // pretty print the result

2035 std::visit(PrintDocVisitor{},ast->root);

2036 }

2037

2038 if (md && md->isFunction())

2039 {

2040 parser->checkUnOrMultipleDocumentedParams();

2041 }

2042 if (parser->context.memberDef) parser->context.memberDef->detectUndocumentedParams(parser->context.hasParamCommand,parser->context.hasReturnCommand);

2043

2044 // reset token

2045 parser->tokenizer.resetToken();

2046

2047 //printf(">>>>>> end validatingParseDoc(%s,%s)\n",ctx?qPrint(ctx->name()):"<none>",

2048 // md?qPrint(md->name()):"<none>");

2049

2050 return ast;

2051}

References Definition::anchor, QCString::at, DocParserContext::autolinkSupport, 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.

Declaration at line 94 of file docparser.h, definition at line 2105 of file docparser.cpp.

2105IDocNodeASTPtr validatingParseText(IDocParser &parserIntf,const QCString &input)

2106{

2107 DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);

2108 assert(parser!=nullptr);

2109 if (parser==nullptr) return nullptr;

2110

2111 // set initial token

2112 parser->context.token = parser->tokenizer.resetToken();

2113

2114 //printf("------------ input ---------\n%s\n"

2115 // "------------ end input -----\n",input);

2116 //parser->context.token = new TokenInfo;

2117 parser->context.context = "";

2118 parser->context.fileName = "<parseText>";

2119 parser->context.relPath = "";

2120 parser->context.memberDef = nullptr;

2121 while (!parser->context.nodeStack.empty()) parser->context.nodeStack.pop();

2122 while (!parser->context.styleStack.empty()) parser->context.styleStack.pop();

2123 while (!parser->context.initialStyleStack.empty()) parser->context.initialStyleStack.pop();

2124 parser->context.inSeeBlock = FALSE;

2125 parser->context.xmlComment = FALSE;

2126 parser->context.insideHtmlLink = FALSE;

2127 parser->context.includeFileText = "";

2128 parser->context.includeFileOffset = 0;

2129 parser->context.includeFileLength = 0;

2130 parser->context.isExample = FALSE;

2131 parser->context.exampleName = "";

2132 parser->context.hasParamCommand = FALSE;

2133 parser->context.hasReturnCommand = FALSE;

2134 parser->context.retvalsFound.clear();

2135 parser->context.paramsFound.clear();

2136 parser->context.searchUrl="";

2137 parser->context.lang = SrcLangExt::Unknown;

2138 parser->context.markdownSupport = Config_getBool(MARKDOWN_SUPPORT);

2139 parser->context.autolinkSupport = FALSE;

2140

2141

2142 auto ast = std::make_unique<DocNodeAST>(DocText(parser));

2143

2144 if (!input.isEmpty())

2145 {

2146 parser->tokenizer.setLineNr(1);

2147 parser->tokenizer.init(input.data(),parser->context.fileName,

2148 parser->context.markdownSupport,parser->context.insideHtmlLink);

2149

2150 // build abstract syntax tree

2151 std::get<DocText>(ast->root).parse();

2152

2153 if (Debug::isFlagSet(Debug::PrintTree))

2154 {

2155 // pretty print the result

2156 std::visit(PrintDocVisitor{},ast->root);

2157 }

2158 }

2159

2160 return ast;

2161}

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, 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

Declaration at line 98 of file docparser.h, definition at line 2053 of file docparser.cpp.

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

2054{

2055 DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);

2056 assert(parser!=nullptr);

2057 if (parser==nullptr) return nullptr;

2058

2059 // set initial token

2060 parser->context.token = parser->tokenizer.resetToken();

2061

2062 //printf("------------ input ---------\n%s\n"

2063 // "------------ end input -----\n",input);

2064 parser->context.context = "";

2065 parser->context.fileName = fileName;

2066 parser->context.relPath = "";

2067 parser->context.memberDef = nullptr;

2068 while (!parser->context.nodeStack.empty()) parser->context.nodeStack.pop();

2069 while (!parser->context.styleStack.empty()) parser->context.styleStack.pop();

2070 while (!parser->context.initialStyleStack.empty()) parser->context.initialStyleStack.pop();

2071 parser->context.inSeeBlock = FALSE;

2072 parser->context.xmlComment = FALSE;

2073 parser->context.insideHtmlLink = FALSE;

2074 parser->context.includeFileText = "";

2075 parser->context.includeFileOffset = 0;

2076 parser->context.includeFileLength = 0;

2077 parser->context.isExample = FALSE;

2078 parser->context.exampleName = "";

2079 parser->context.hasParamCommand = FALSE;

2080 parser->context.hasReturnCommand = FALSE;

2081 parser->context.retvalsFound.clear();

2082 parser->context.paramsFound.clear();

2083 parser->context.searchUrl="";

2084 parser->context.lang = SrcLangExt::Unknown;

2085 parser->context.markdownSupport = Config_getBool(MARKDOWN_SUPPORT);

2086 parser->context.autolinkSupport = false;

2087

2088 auto ast = std::make_unique<DocNodeAST>(DocTitle(parser,nullptr));

2089

2090 if (!input.isEmpty())

2091 {

2092 // build abstract syntax tree from title string

2093 std::get<DocTitle>(ast->root).parseFromString(nullptr,input);

2094

2095 if (Debug::isFlagSet(Debug::PrintTree))

2096 {

2097 // pretty print the result

2098 std::visit(PrintDocVisitor{},ast->root);

2099 }

2100 }

2101

2102 return ast;

2103}

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::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.

---

Generated via doxygen2docusaurus by Doxygen 1.14.0.