Doxygen
Loading...
Searching...
No Matches
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()

◆ createRef()

IDocNodeASTPtr createRef ( IDocParser & parser,
const QCString & target,
const QCString & context,
const QCString & srcFile = "",
int srcLine = -1 )

Definition at line 2171 of file docparser.cpp.

2172{
2173 DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);
2174 assert(parser!=nullptr);
2175 if (parser==nullptr) return nullptr;
2176 if (!srcFile.isEmpty())
2177 {
2178 parser->context.fileName = srcFile;
2179 parser->tokenizer.setLineNr(srcLine);
2180 }
2181 return std::make_unique<DocNodeAST>(DocRef(parser,nullptr,target,context));
2182}
DocTokenizer tokenizer
DocParserContext context
Node representing a reference to some item.
Definition docnode.h:778
void setLineNr(int lineno)
bool isEmpty() const
Returns TRUE iff the string is empty.
Definition qcstring.h:163
QCString fileName
Definition docparser_p.h:71

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 )

◆ 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
parserIntfThe parser object created via createDocParser()
fileNameFile in which the documentation block is found (or the name of the example file in case isExample is TRUE).
startLineLine at which the documentation block is found.
ctxClass or namespace to which this block belongs.
mdMember definition to which the documentation belongs. Can be 0.
inputString representation of the documentation block.
optionsOptional parameters.
Returns
An object representing the abstract syntax tree. Ownership of the pointer is handed over to the caller.

Definition at line 1928 of file docparser.cpp.

1935{
1936 DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);
1937 assert(parser!=nullptr);
1938 if (parser==nullptr) return nullptr;
1939 //printf("validatingParseDoc(%s,%s)=[%s]\n",ctx?qPrint(ctx->name()):"<none>",
1940 // md?qPrint(md->name()):"<none>",
1941 // qPrint(input));
1942 //printf("========== validating %s at line %d\n",qPrint(fileName),startLine);
1943 //printf("---------------- input --------------------\n%s\n----------- end input -------------------\n",qPrint(input));
1944
1945 // set initial token
1946 parser->context.token = parser->tokenizer.resetToken();
1947
1948 if (ctx && ctx!=Doxygen::globalScope &&
1951 )
1952 )
1953 {
1955 }
1956 else if (ctx && ctx->definitionType()==Definition::TypePage)
1957 {
1958 const Definition *scope = (toPageDef(ctx))->getPageScope();
1959 if (scope && scope!=Doxygen::globalScope)
1960 {
1961 parser->context.context = substitute(scope->name(),getLanguageSpecificSeparator(scope->getLanguage(),true),"::");
1962 }
1963 }
1964 else if (ctx && ctx->definitionType()==Definition::TypeGroup)
1965 {
1966 const Definition *scope = (toGroupDef(ctx))->getGroupScope();
1967 if (scope && scope!=Doxygen::globalScope)
1968 {
1969 parser->context.context = substitute(scope->name(),getLanguageSpecificSeparator(scope->getLanguage(),true),"::");
1970 }
1971 }
1972 else
1973 {
1974 parser->context.context = "";
1975 }
1976 parser->context.scope = ctx;
1977 parser->context.lang = getLanguageFromFileName(fileName);
1978
1979 if (options.indexWords() && Doxygen::searchIndex.enabled())
1980 {
1981 if (md)
1982 {
1983 parser->context.searchUrl=md->getOutputFileBase();
1984 Doxygen::searchIndex.setCurrentDoc(md,md->anchor(),false);
1985 }
1986 else if (ctx)
1987 {
1988 parser->context.searchUrl=ctx->getOutputFileBase();
1989 Doxygen::searchIndex.setCurrentDoc(ctx,ctx->anchor(),false);
1990 }
1991 }
1992 else
1993 {
1994 parser->context.searchUrl="";
1995 }
1996
1997 parser->context.fileName = fileName;
1998 parser->context.relPath = (!options.linkFromIndex() && ctx) ?
2000 QCString("");
2001 //printf("ctx->name=%s relPath=%s\n",qPrint(ctx->name()),qPrint(parser->context.relPath));
2002 parser->context.memberDef = md;
2003 while (!parser->context.nodeStack.empty()) parser->context.nodeStack.pop();
2004 while (!parser->context.styleStack.empty()) parser->context.styleStack.pop();
2005 while (!parser->context.initialStyleStack.empty()) parser->context.initialStyleStack.pop();
2006 parser->context.inSeeBlock = FALSE;
2007 parser->context.inCodeStyle = FALSE;
2008 parser->context.xmlComment = FALSE;
2009 parser->context.insideHtmlLink = FALSE;
2010 parser->context.includeFileText = "";
2011 parser->context.includeFileOffset = 0;
2012 parser->context.includeFileLength = 0;
2013 parser->context.isExample = options.isExample();
2014 parser->context.exampleName = options.exampleName();
2015 parser->context.hasParamCommand = FALSE;
2016 parser->context.hasReturnCommand = FALSE;
2017 parser->context.retvalsFound.clear();
2018 parser->context.paramsFound.clear();
2019 parser->context.markdownSupport = options.markdownSupport();
2020 parser->context.autolinkSupport = options.autolinkSupport();
2021
2022 //printf("Starting comment block at %s:%d\n",qPrint(parser->context.fileName),startLine);
2023 parser->tokenizer.setLineNr(startLine);
2024 size_t ioLen = input.length();
2025 QCString inpStr = parser->processCopyDoc(input.data(),ioLen);
2026 if (inpStr.isEmpty() || inpStr.at(inpStr.length()-1)!='\n')
2027 {
2028 inpStr+='\n';
2029 }
2030 //printf("processCopyDoc(in='%s' out='%s')\n",qPrint(input),qPrint(inpStr));
2031 parser->tokenizer.init(inpStr.data(),parser->context.fileName,
2033
2034 // build abstract syntax tree
2035 auto ast = std::make_unique<DocNodeAST>(DocRoot(parser,md!=nullptr,options.singleLine()));
2036 std::get<DocRoot>(ast->root).parse();
2037
2039 {
2040 // pretty print the result
2041 std::visit(PrintDocVisitor{},ast->root);
2042 }
2043
2044 if (md && md->isFunction())
2045 {
2046 parser->checkUnOrMultipleDocumentedParams();
2047 }
2049
2050 // reset token
2051 parser->tokenizer.resetToken();
2052
2053 //printf(">>>>>> end validatingParseDoc(%s,%s)\n",ctx?qPrint(ctx->name()):"<none>",
2054 // md?qPrint(md->name()):"<none>");
2055
2056 return ast;
2057}
@ PrintTree
Definition debug.h:34
static bool isFlagSet(const DebugMask mask)
Definition debug.cpp:132
The common base class of all entity definitions found in the sources.
Definition definition.h:76
virtual SrcLangExt getLanguage() const =0
Returns the programming language this definition was written in.
virtual DefType definitionType() const =0
virtual QCString anchor() const =0
virtual QCString qualifiedName() const =0
virtual QCString getOutputFileBase() const =0
virtual const QCString & name() const =0
QCString processCopyDoc(const char *data, size_t &len)
Root node of documentation tree.
Definition docnode.h:1313
void init(const char *input, const QCString &fileName, bool markdownSupport, bool insideHtmlLink)
TokenInfo * resetToken()
static NamespaceDefMutable * globalScope
Definition doxygen.h:121
static SearchIndexIntf searchIndex
Definition doxygen.h:124
virtual bool isFunction() const =0
virtual void detectUndocumentedParams(bool hasParamCommand, bool hasReturnCommand) const =0
This is an alternative implementation of QCString.
Definition qcstring.h:101
size_t length() const
Returns the length of the string, not counting the 0-terminator.
Definition qcstring.h:166
const char * data() const
Returns a pointer to the contents of the string in the form of a 0-terminated C string.
Definition qcstring.h:172
GroupDef * toGroupDef(Definition *d)
PageDef * toPageDef(Definition *d)
Definition pagedef.cpp:481
QCString substitute(const QCString &s, const QCString &src, const QCString &dst)
substitute all occurrences of src in s by dst
Definition qcstring.cpp:482
#define FALSE
Definition qcstring.h:34
bool autolinkSupport() const
Definition docoptions.h:32
bool linkFromIndex() const
Definition docoptions.h:30
bool markdownSupport() const
Definition docoptions.h:31
QCString exampleName() const
Definition docoptions.h:28
bool indexWords() const
Definition docoptions.h:26
bool singleLine() const
Definition docoptions.h:29
bool isExample() const
Definition docoptions.h:27
StringMultiSet retvalsFound
Definition docparser_p.h:76
DocStyleChangeStack styleStack
Definition docparser_p.h:68
size_t includeFileLength
Definition docparser_p.h:88
DocNodeStack nodeStack
Definition docparser_p.h:67
StringMultiSet paramsFound
Definition docparser_p.h:77
QCString exampleName
Definition docparser_p.h:80
const Definition * scope
Definition docparser_p.h:61
QCString includeFileText
Definition docparser_p.h:86
TokenInfo * token
Definition docparser_p.h:93
DocStyleChangeStack initialStyleStack
Definition docparser_p.h:69
SrcLangExt lang
Definition docparser_p.h:83
QCString searchUrl
Definition docparser_p.h:81
size_t includeFileOffset
Definition docparser_p.h:87
const MemberDef * memberDef
Definition docparser_p.h:78
SrcLangExt getLanguageFromFileName(const QCString &fileName, SrcLangExt defLang)
Definition util.cpp:5107
QCString relativePathToRoot(const QCString &name)
Definition util.cpp:3500
QCString getLanguageSpecificSeparator(SrcLangExt lang, bool classScope)
Returns the scope separator to use given the programming language lang.
Definition util.cpp:5809

References Definition::anchor(), QCString::at(), DocOptions::autolinkSupport(), DocParserContext::autolinkSupport, DocParser::checkUnOrMultipleDocumentedParams(), DocParser::context, DocParserContext::context, QCString::data(), 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, 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::paramsFound, Debug::PrintTree, DocParser::processCopyDoc(), Definition::qualifiedName(), relativePathToRoot(), DocParserContext::relPath, DocTokenizer::resetToken(), DocParserContext::retvalsFound, DocParserContext::scope, Doxygen::searchIndex, DocParserContext::searchUrl, DocTokenizer::setLineNr(), DocOptions::singleLine(), 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 2112 of file docparser.cpp.

2113{
2114 DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);
2115 assert(parser!=nullptr);
2116 if (parser==nullptr) return nullptr;
2117
2118 // set initial token
2119 parser->context.token = parser->tokenizer.resetToken();
2120
2121 //printf("------------ input ---------\n%s\n"
2122 // "------------ end input -----\n",input);
2123 //parser->context.token = new TokenInfo;
2124 parser->context.context = "";
2125 parser->context.fileName = "<parseText>";
2126 parser->context.relPath = "";
2127 parser->context.memberDef = nullptr;
2128 while (!parser->context.nodeStack.empty()) parser->context.nodeStack.pop();
2129 while (!parser->context.styleStack.empty()) parser->context.styleStack.pop();
2130 while (!parser->context.initialStyleStack.empty()) parser->context.initialStyleStack.pop();
2131 parser->context.inSeeBlock = FALSE;
2132 parser->context.inCodeStyle = FALSE;
2133 parser->context.xmlComment = FALSE;
2134 parser->context.insideHtmlLink = FALSE;
2135 parser->context.includeFileText = "";
2136 parser->context.includeFileOffset = 0;
2137 parser->context.includeFileLength = 0;
2138 parser->context.isExample = FALSE;
2139 parser->context.exampleName = "";
2140 parser->context.hasParamCommand = FALSE;
2141 parser->context.hasReturnCommand = FALSE;
2142 parser->context.retvalsFound.clear();
2143 parser->context.paramsFound.clear();
2144 parser->context.searchUrl="";
2145 parser->context.lang = SrcLangExt::Unknown;
2146 parser->context.markdownSupport = Config_getBool(MARKDOWN_SUPPORT);
2147 parser->context.autolinkSupport = FALSE;
2148
2149
2150 auto ast = std::make_unique<DocNodeAST>(DocText(parser));
2151
2152 if (!input.isEmpty())
2153 {
2154 parser->tokenizer.setLineNr(1);
2155 parser->tokenizer.init(input.data(),parser->context.fileName,
2157
2158 // build abstract syntax tree
2159 std::get<DocText>(ast->root).parse();
2160
2162 {
2163 // pretty print the result
2164 std::visit(PrintDocVisitor{},ast->root);
2165 }
2166 }
2167
2168 return ast;
2169}
Root node of a text fragment.
Definition docnode.h:1304
#define Config_getBool(name)
Definition config.h:33

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 2059 of file docparser.cpp.

2060{
2061 DocParser *parser = dynamic_cast<DocParser*>(&parserIntf);
2062 assert(parser!=nullptr);
2063 if (parser==nullptr) return nullptr;
2064
2065 // set initial token
2066 parser->context.token = parser->tokenizer.resetToken();
2067
2068 //printf("------------ input ---------\n%s\n"
2069 // "------------ end input -----\n",input);
2070 parser->context.context = "";
2071 parser->context.fileName = fileName;
2072 parser->context.relPath = "";
2073 parser->context.memberDef = nullptr;
2074 while (!parser->context.nodeStack.empty()) parser->context.nodeStack.pop();
2075 while (!parser->context.styleStack.empty()) parser->context.styleStack.pop();
2076 while (!parser->context.initialStyleStack.empty()) parser->context.initialStyleStack.pop();
2077 parser->context.inSeeBlock = FALSE;
2078 parser->context.inCodeStyle = FALSE;
2079 parser->context.xmlComment = FALSE;
2080 parser->context.insideHtmlLink = FALSE;
2081 parser->context.includeFileText = "";
2082 parser->context.includeFileOffset = 0;
2083 parser->context.includeFileLength = 0;
2084 parser->context.isExample = FALSE;
2085 parser->context.exampleName = "";
2086 parser->context.hasParamCommand = FALSE;
2087 parser->context.hasReturnCommand = FALSE;
2088 parser->context.retvalsFound.clear();
2089 parser->context.paramsFound.clear();
2090 parser->context.searchUrl="";
2091 parser->context.lang = SrcLangExt::Unknown;
2092 parser->context.markdownSupport = Config_getBool(MARKDOWN_SUPPORT);
2093 parser->context.autolinkSupport = false;
2094
2095 auto ast = std::make_unique<DocNodeAST>(DocTitle(parser,nullptr));
2096
2097 if (!input.isEmpty())
2098 {
2099 // build abstract syntax tree from title string
2100 std::get<DocTitle>(ast->root).parseFromString(nullptr,input);
2101
2103 {
2104 // pretty print the result
2105 std::visit(PrintDocVisitor{},ast->root);
2106 }
2107 }
2108
2109 return ast;
2110}
Node representing a simple section title.
Definition docnode.h:608

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().