Doxygen
Loading...
Searching...
No Matches
CommentScanner Class Reference

#include <src/commentscan.h>

Classes

struct  Private

Public Member Functions

 CommentScanner ()
 ~CommentScanner ()
bool parseCommentBlock (OutlineParserInterface *parser, Entry *curEntry, const DString &comment, const DString &fileName, int &lineNr, bool isBrief, bool isJavadocStyle, bool isInbody, Protection &prot, int &position, bool &newEntryNeeded, bool markdownEnabled, GuardedSectionStack *guards)
 Invokes the comment block parser with the request to parse a single comment block.
void initGroupInfo (Entry *entry)
void enterFile (const DString &fileName, int lineNr)
void leaveFile (const DString &fileName, int lineNr)
void enterCompound (const DString &fileName, int line, const DString &name)
void leaveCompound (const DString &fileName, int line, const DString &name)
void open (Entry *e, const DString &fileName, int line, bool implicit=false)
void close (Entry *e, const DString &fileName, int line, bool foundInline, bool implicit=false)
void addDeprecatedDocs (Entry *current, const DString &fileName, int line, OutlineParserInterface *parser)

Static Public Member Functions

static bool isCommand (const DString &cmdName)

Private Attributes

std::unique_ptr< Private > p

Detailed Description

Definition at line 53 of file commentscan.h.

Constructor & Destructor Documentation

◆ CommentScanner()

CommentScanner::CommentScanner ( )

Definition at line 4979 of file commentscan.l.

4979 : p(std::make_unique<Private>())
4980{
4981 commentscanYYlex_init_extra(&p->extra,&p->yyscanner);
4982#ifdef FLEX_DEBUG
4983 commentscanYYset_debug(Debug::isFlagSet(Debug::Lex_commentscan)?1:0,p->yyscanner);
4984#endif
4985}
std::unique_ptr< Private > p
@ Lex_commentscan
Definition debug.h:56
static bool isFlagSet(const DebugMask mask)
Definition debug.cpp:132

References Debug::isFlagSet(), Debug::Lex_commentscan, and p.

◆ ~CommentScanner()

CommentScanner::~CommentScanner ( )

Definition at line 4987 of file commentscan.l.

4988{
4989 commentscanYYlex_destroy(p->yyscanner);
4990}

References p.

Member Function Documentation

◆ addDeprecatedDocs()

void CommentScanner::addDeprecatedDocs ( Entry * current,
const DString & fileName,
int line,
OutlineParserInterface * parser )

Definition at line 5221 of file commentscan.l.

5222{
5223 static reg::Ex deprecated_re(R"(deprecated\s*(\‍(\s*\"([^\"]*)\"\s*\))?)");
5224 reg::Match match;
5225 std::string attr = current->attributes.str();
5226 if (reg::search(attr,match,deprecated_re))
5227 {
5228 DString docs;
5229 if (match.size()==3) // deprecated attribute with documentation
5230 {
5231 Markdown markdown(fileName,line);
5232 DString rawDoc = match[2].str();
5233 DString processedDoc = Config_getBool(MARKDOWN_SUPPORT) ? markdown.process(rawDoc,line) : rawDoc;
5234 std::shared_ptr<Entry> docEntry = std::make_shared<Entry>();
5235 GuardedSectionStack guards;
5236 bool newEntryNeeded = false;
5237 Protection prot = Protection::Public;
5238 int position=0;
5239 parseCommentBlock(parser,
5240 docEntry.get(),
5241 processedDoc,
5242 fileName,
5243 line,
5244 false, // isBrief
5245 false, // isAutoBriefOn
5246 false, // isInbody
5247 prot,
5248 position,
5249 newEntryNeeded,
5250 Config_getBool(MARKDOWN_SUPPORT), // markdownSupport
5251 &guards);
5252 docs = docEntry->doc;
5253 //printf("rawDoc='%s' processedDoc='%s' docs='%s'\n",qPrint(rawDoc),qPrint(processedDoc),qPrint(docs));
5254 }
5255 else // deprecated attribute without documentation
5256 {
5257 current->spec.setDeprAttr(true);
5258 }
5259 if (!docs.empty() || !current->spec.isDeprDoc()) // attribute has docs
5260 // or no @deprecated command found in comment yet
5261 {
5262 // add new deprecated xref item to the documentation of this entry
5263 addXRefItemToEntry(current,
5264 docs,
5265 "deprecated",
5268 false, // append
5269 false, // inBody
5270 line);
5271 }
5272 }
5273 else
5274 {
5275 //printf("no match in attributes='%s'\n",qPrint(attr));
5276 }
5277}
bool parseCommentBlock(OutlineParserInterface *parser, Entry *curEntry, const DString &comment, const DString &fileName, int &lineNr, bool isBrief, bool isJavadocStyle, bool isInbody, Protection &prot, int &position, bool &newEntryNeeded, bool markdownEnabled, GuardedSectionStack *guards)
Invokes the comment block parser with the request to parse a single comment block.
bool empty() const
Returns true iff the string is empty (std::string compatible alias for isEmpty()).
Definition dstring.h:148
const std::string & str() const
Definition dstring.h:645
DString attributes
member's attributes (e.g. [[nodiscard]])
Definition entry.h:193
TypeSpecifier spec
class/member specifiers
Definition entry.h:181
virtual DString trDeprecatedList()=0
virtual DString trDeprecated()=0
std::stack< GuardedSection > GuardedSectionStack
Definition commentscan.h:48
static void addXRefItemToEntry(Entry *current, const DString &docs, const DString &baseName, const DString &itemTitle, const DString &listTitle, bool append, bool inBody, int lineNr)
#define Config_getBool(name)
Definition config.h:33
Translator * theTranslator
Definition language.cpp:76
bool search(std::string_view str, Match &match, const Ex &re, size_t pos)
Search in a given string str starting at position pos for a match against regular expression re.
Definition regex.cpp:850
bool match(std::string_view str, Match &match, const Ex &re)
Matches a given string str for a match against regular expression re.
Definition regex.cpp:861
Protection
Definition types.h:32

References addXRefItemToEntry(), Entry::attributes, Config_getBool, DString::empty(), parseCommentBlock(), Markdown::process(), reg::search(), Entry::spec, DString::str(), theTranslator, Translator::trDeprecated(), and Translator::trDeprecatedList().

◆ close()

void CommentScanner::close ( Entry * e,
const DString & fileName,
int line,
bool foundInline,
bool implicit = false )

Definition at line 5210 of file commentscan.l.

5211{
5212 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5213 yyextra->docGroup.close(e,fileName,lineNr,foundInline,implicit);
5214}

References p.

◆ enterCompound()

void CommentScanner::enterCompound ( const DString & fileName,
int line,
const DString & name )

Definition at line 5192 of file commentscan.l.

5193{
5194 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5195 yyextra->docGroup.enterCompound(fileName,lineNr,name);
5196}

References p.

◆ enterFile()

void CommentScanner::enterFile ( const DString & fileName,
int lineNr )

Definition at line 5180 of file commentscan.l.

5181{
5182 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5183 yyextra->docGroup.enterFile(fileName,lineNr);
5184}

References p.

Referenced by generateHtmlForComment().

◆ initGroupInfo()

void CommentScanner::initGroupInfo ( Entry * entry)

Definition at line 5174 of file commentscan.l.

5175{
5176 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5177 yyextra->docGroup.initGroupInfo(entry);
5178}

References p.

◆ isCommand()

bool CommentScanner::isCommand ( const DString & cmdName)
static

Definition at line 5216 of file commentscan.l.

5217{
5218 return (docCmdMap.find(cmdName.str()) != docCmdMap.end());
5219}
static const std::unordered_map< std::string, DocCmdMap > docCmdMap

References docCmdMap, and DString::str().

Referenced by Markdown::Private::processLink().

◆ leaveCompound()

void CommentScanner::leaveCompound ( const DString & fileName,
int line,
const DString & name )

Definition at line 5198 of file commentscan.l.

5199{
5200 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5201 yyextra->docGroup.leaveCompound(fileName,lineNr,name);
5202}

References p.

◆ leaveFile()

void CommentScanner::leaveFile ( const DString & fileName,
int lineNr )

Definition at line 5186 of file commentscan.l.

5187{
5188 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5189 yyextra->docGroup.leaveFile(fileName,lineNr);
5190}

References p.

Referenced by generateHtmlForComment().

◆ open()

void CommentScanner::open ( Entry * e,
const DString & fileName,
int line,
bool implicit = false )

Definition at line 5204 of file commentscan.l.

5205{
5206 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5207 yyextra->docGroup.open(e,fileName,lineNr,implicit);
5208}

References p.

◆ parseCommentBlock()

bool CommentScanner::parseCommentBlock ( OutlineParserInterface * parser,
Entry * curEntry,
const DString & comment,
const DString & fileName,
int & lineNr,
bool isBrief,
bool isJavadocStyle,
bool isInbody,
Protection & prot,
int & position,
bool & newEntryNeeded,
bool markdownEnabled,
GuardedSectionStack * guards )

Invokes the comment block parser with the request to parse a single comment block.

Parameters
[in]parserThe language parse that invoked this function. The comment block parse may invoke ParserInterface::parsePrototype() in order to parse the argument of a @fn command.
[in]curEntryThe Entry to which the comment block belongs. Any information (like documentation) that is found in the comment block will be stored in this entry.
[in]commentA string representing the actual comment block. Note that leading *'s are already stripped from the comment block.
[in]fileNameThe name of the file in which the comment is found. Mainly used for producing warnings.
[in,out]lineNrThe line number at which the comment block was found. When the function returns it will be set to the last line parsed.
[in]isBrieftrue iff this comment block represents a brief description.
[in]isJavadocStyletrue iff this comment block is in "Javadoc" style. This means that it starts as a brief description until the end of the sentences is found and then proceeds as a detailed description.
[in]isInbodytrue iff this comment block is located in the body of a function.
[in,out]protThe protection level in which this comment block was found. Commands in the comment block may override this.
[in,out]positionThe character position within comment where the comment block starts. Typically used in case the comment block contains multiple structural commands.
[out]newEntryNeededBoolean that is true if the comment block parser finds that a the comment block finishes the entry and a new one needs to be started.
[in]markdownEnabledIndicates if markdown specific processing should be done.
[in,out]guardsTracks nested conditional sections (if,ifnot,..)
Returns
true if the comment requires further processing. The parameter newEntryNeeded will typically be true in this case and position will indicate the offset inside the comment string where to proceed parsing. false indicates no further processing is needed.

Definition at line 4992 of file commentscan.l.

5006{
5007 AUTO_TRACE("comment='{}' fileName={} lineNr={} isBrief={} isAutoBriefOn={} inInbody={}"
5008 " prot={} markdownSupport={}",Trace::trunc(comment),fileName,lineNr,isBrief,
5009 isAutoBriefOn,isInbody,prot,markdownSupport);
5010 yyscan_t yyscanner = p->yyscanner;
5011 struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
5012
5013 initParser(yyscanner);
5014 yyextra->guards = guards;
5015 yyextra->langParser = parser;
5016 yyextra->current = curEntry;
5017 yyextra->current->docLine = (lineNr > 1 ? lineNr : 1);
5018 if (comment.empty()) return false; // avoid empty strings
5019 yyextra->inputString = comment;
5020 yyextra->inputString.append(" ");
5021 yyextra->inputPosition = position;
5022 yyextra->lineNr = lineNr;
5023 yyextra->fileName = fileName;
5024 yyextra->protection = prot;
5025 yyextra->needNewEntry = false;
5026 yyextra->xrefKind = XRef_None;
5027 yyextra->xrefAppendFlag = false;
5028 yyextra->insidePre = false;
5029 yyextra->parseMore = false;
5030 yyextra->inBody = isInbody;
5031 yyextra->markdownSupport= markdownSupport;
5032 yyextra->outputXRef.clear();
5033 if (!isBrief && !isAutoBriefOn && !yyextra->current->doc.empty())
5034 { // add newline separator between detailed comment blocks
5035 yyextra->current->doc += '\n';
5036 }
5037 setOutput(yyscanner, isBrief || isAutoBriefOn ? OutputBrief : OutputDoc );
5038 yyextra->briefEndsAtDot = isAutoBriefOn;
5039 yyextra->condCount = 0;
5040 yyextra->sectionLevel = 0;
5041 yyextra->spaceBeforeCmd.clear();
5042 yyextra->spaceBeforeIf.clear();
5043 yyextra->htmlContextStack.clear();
5044
5045 DebugLex debugLex(Debug::Lex_commentscan, __FILE__, !fileName.empty() ? qPrint(fileName): nullptr);
5046 if (!yyextra->current->inbodyDocs.empty() && isInbody) // separate in body fragments
5047 {
5048 char cmd[30];
5049 snprintf(cmd,30,"\n\n\\iline %d \\ilinebr ",lineNr);
5050 yyextra->current->inbodyDocs+=cmd;
5051 }
5052
5053 Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\n"
5054 "input=[\n{}]\n",fileName,lineNr,yyextra->inputString
5055 );
5056
5057 commentscanYYrestart( nullptr, yyscanner );
5058 BEGIN( Comment );
5059 commentscanYYlex(yyscanner);
5060 setOutput(yyscanner, OutputDoc );
5061
5062 if (YY_START==OverloadParam) // comment ended with \overload
5063 {
5065 }
5066
5067 if (yyextra->insideParBlock)
5068 {
5069 warn(yyextra->fileName,yyextra->lineNr,
5070 "Documentation block ended while inside a \\parblock. Missing \\endparblock");
5071 }
5072
5073 yyextra->current->doc=stripLeadingAndTrailingEmptyLines(yyextra->current->doc,yyextra->current->docLine);
5074 yyextra->current->brief=stripLeadingAndTrailingEmptyLines(yyextra->current->brief,yyextra->current->docLine);
5075
5076 if (yyextra->current->section.isFileDoc() && yyextra->current->doc.empty())
5077 {
5078 // to allow a comment block with just a @file command.
5079 yyextra->current->doc="\n\n";
5080 }
5081
5082 if (yyextra->current->section.isMemberGrp() &&
5083 yyextra->docGroup.empty()) // @name section but no group started yet
5084 {
5085 yyextra->docGroup.open(yyextra->current,yyextra->fileName,yyextra->lineNr,true);
5086 }
5087
5088 Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\noutput=[\n"
5089 "brief=[line={}\n{}]\ndocs=[line={}\n{}]\ninbody=[line={}\n{}]\n]\n===========\n",
5090 fileName,lineNr,
5091 yyextra->current->briefLine,yyextra->current->brief,
5092 yyextra->current->docLine,yyextra->current->doc,
5093 yyextra->current->inbodyLine,yyextra->current->inbodyDocs
5094 );
5095
5096 checkFormula(yyscanner);
5097 prot = yyextra->protection;
5098
5099 yyextra->docGroup.addDocs(curEntry);
5100
5101 newEntryNeeded = yyextra->needNewEntry;
5102
5103 // if we did not proceed during this call, it does not make
5104 // sense to continue, since we get stuck. See bug 567346 for situations
5105 // were this happens
5106 if (yyextra->parseMore && position==yyextra->inputPosition) yyextra->parseMore=false;
5107
5108 if (!yyextra->parseMore && !yyextra->guards->empty())
5109 {
5110 warn(yyextra->fileName,yyextra->lineNr,"Documentation block ended in the middle of a conditional section!");
5111 }
5112
5113 if (yyextra->parseMore) position=yyextra->inputPosition; else position=0;
5114
5115 lineNr = yyextra->lineNr;
5116 AUTO_TRACE_EXIT("position={} parseMore={} newEntryNeeded={}",
5117 position,yyextra->parseMore,newEntryNeeded);
5118
5119 return yyextra->parseMore;
5120}
void clear()
Definition dstring.h:214
DString & append(char c)
Definition dstring.h:489
@ CommentScan
Definition debug.h:33
static void print(DebugMask mask, int prio, fmt::format_string< Args... > fmt, Args &&... args)
Definition debug.h:78
int docLine
line number at which the documentation was found
Definition entry.h:201
virtual DString trOverloadText()=0
yyguts_t * yyscan_t
Definition code.l:24
@ XRef_None
static void setOutput(yyscan_t yyscanner, OutputContext ctx)
static void initParser(yyscan_t yyscanner)
static void addOutput(yyscan_t yyscanner, const char *s)
@ OutputDoc
@ OutputBrief
static void checkFormula(yyscan_t yyscanner)
#define AUTO_TRACE(...)
Definition docnode.cpp:53
#define AUTO_TRACE_EXIT(...)
Definition docnode.cpp:55
const char * qPrint(const char *s)
Definition dstring.h:783
#define warn(file, line, fmt,...)
Definition message.h:97
DString trunc(const DString &s, size_t numChars=15)
Definition trace.h:56
DString stripLeadingAndTrailingEmptyLines(const DString &s, int &docLine)
Special version of DString::stripWhiteSpace() that only strips completely blank lines.
Definition util.cpp:3996

References addOutput(), DString::append(), AUTO_TRACE, AUTO_TRACE_EXIT, checkFormula(), Debug::CommentScan, Entry::docLine, DString::empty(), initParser(), Debug::Lex_commentscan, OutputBrief, OutputDoc, p, Debug::print(), qPrint(), setOutput(), stripLeadingAndTrailingEmptyLines(), theTranslator, Translator::trOverloadText(), Trace::trunc(), warn, and XRef_None.

Referenced by addDeprecatedDocs(), generateHtmlForComment(), and CitationManager::generatePage().

Member Data Documentation

◆ p

std::unique_ptr<Private> CommentScanner::p
private

The documentation for this class was generated from the following files: