The CommentScanner Class Reference

Declaration

class CommentScanner { ... }

Included Headers

#include <src/commentscan.h>

Public Constructors Index

	CommentScanner ()

Public Destructor Index

	~CommentScanner ()

Public Member Functions Index

bool	parseCommentBlock (OutlineParserInterface *parser, Entry *curEntry, const QCString &comment, const QCString &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. More...
void	initGroupInfo (Entry *entry)
void	enterFile (const QCString &fileName, int lineNr)
void	leaveFile (const QCString &fileName, int lineNr)
void	enterCompound (const QCString &fileName, int line, const QCString &name)
void	leaveCompound (const QCString &fileName, int line, const QCString &name)
void	open (Entry *e, const QCString &fileName, int line, bool implicit=false)
void	close (Entry *e, const QCString &fileName, int line, bool foundInline, bool implicit=false)

Private Member Attributes Index

std::unique_ptr< Private >	p

Definition at line 53 of file commentscan.h.

Public Constructors

CommentScanner()

CommentScanner::CommentScanner ()

Declaration at line 56 of file commentscan.h, definition at line 4703 of file commentscan.l.

4703CommentScanner::CommentScanner() : p(std::make_unique<Private>())

4704{

4705 commentscanYYlex_init_extra(&p->extra,&p->yyscanner);

4706#ifdef FLEX_DEBUG

4707 commentscanYYset_debug(Debug::isFlagSet(Debug::Lex_commentscan)?1:0,p->yyscanner);

4708#endif

4709}

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

Public Destructor

~CommentScanner()

CommentScanner::~CommentScanner ()

Declaration at line 57 of file commentscan.h, definition at line 4711 of file commentscan.l.

4711CommentScanner::~CommentScanner()

4712{

4713 commentscanYYlex_destroy(p->yyscanner);

4714}

Reference p.

Public Member Functions

close()

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

Declaration at line 117 of file commentscan.h, definition at line 4934 of file commentscan.l.

4934void CommentScanner::close(Entry *e,const QCString &fileName,int lineNr,bool foundInline,bool implicit)

4935{

4936 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;

4937 yyextra->docGroup.close(e,fileName,lineNr,foundInline,implicit);

4938}

Reference p.

enterCompound()

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

Declaration at line 114 of file commentscan.h, definition at line 4916 of file commentscan.l.

4916void CommentScanner::enterCompound(const QCString &fileName,int lineNr,const QCString &name)

4917{

4918 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;

4919 yyextra->docGroup.enterCompound(fileName,lineNr,name);

4920}

Reference p.

enterFile()

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

Declaration at line 112 of file commentscan.h, definition at line 4904 of file commentscan.l.

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

4905{

4906 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;

4907 yyextra->docGroup.enterFile(fileName,lineNr);

4908}

Reference p.

Referenced by generateHtmlForComment.

initGroupInfo()

void CommentScanner::initGroupInfo (Entry * entry)

Declaration at line 111 of file commentscan.h, definition at line 4898 of file commentscan.l.

4898void CommentScanner::initGroupInfo(Entry *entry)

4899{

4900 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;

4901 yyextra->docGroup.initGroupInfo(entry);

4902}

Reference p.

leaveCompound()

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

Declaration at line 115 of file commentscan.h, definition at line 4922 of file commentscan.l.

4922void CommentScanner::leaveCompound(const QCString &fileName,int lineNr,const QCString &name)

4923{

4924 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;

4925 yyextra->docGroup.leaveCompound(fileName,lineNr,name);

4926}

Reference p.

leaveFile()

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

Declaration at line 113 of file commentscan.h, definition at line 4910 of file commentscan.l.

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

4911{

4912 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;

4913 yyextra->docGroup.leaveFile(fileName,lineNr);

4914}

Reference p.

Referenced by generateHtmlForComment.

open()

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

Declaration at line 116 of file commentscan.h, definition at line 4928 of file commentscan.l.

4928void CommentScanner::open(Entry *e,const QCString &fileName,int lineNr,bool implicit)

4929{

4930 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;

4931 yyextra->docGroup.open(e,fileName,lineNr,implicit);

4932}

Reference p.

parseCommentBlock()

bool CommentScanner::parseCommentBlock (OutlineParserInterface * parser, Entry * curEntry, const QCString & comment, const QCString & 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] parser	The 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] curEntry	The 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] comment	A string representing the actual comment block. Note that leading *'s are already stripped from the comment block.
[in] fileName	The name of the file in which the comment is found. Mainly used for producing warnings.
[inout] lineNr	The line number at which the comment block was found. When the function returns it will be set to the last line parsed.
[in] isBrief	TRUE iff this comment block represents a brief description.
[in] isJavadocStyle	TRUE 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] isInbody	TRUE iff this comment block is located in the body of a function.
[inout] prot	The protection level in which this comment block was found. Commands in the comment block may override this.
[inout] position	The character position within comment where the comment block starts. Typically used in case the comment block contains multiple structural commands.
[out] newEntryNeeded	Boolean 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] markdownEnabled	Indicates if markdown specific processing should be done.
[inout] guards	Tracks 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.

Declaration at line 97 of file commentscan.h, definition at line 4716 of file commentscan.l.

4716bool CommentScanner::parseCommentBlock(/* in */ OutlineParserInterface *parser,

4717 /* in */ Entry *curEntry,

4718 /* in */ const QCString &comment,

4719 /* in */ const QCString &fileName,

4720 /* in,out */ int &lineNr,

4721 /* in */ bool isBrief,

4722 /* in */ bool isAutoBriefOn,

4723 /* in */ bool isInbody,

4724 /* in,out */ Protection &prot,

4725 /* in,out */ int &position,

4726 /* out */ bool &newEntryNeeded,

4727 /* in */ bool markdownSupport,

4728 /* inout */ GuardedSectionStack *guards

4729 )

4730{

4731 AUTO_TRACE("comment='{}' fileName={} lineNr={} isBrief={} isAutoBriefOn={} inInbody={}"

4732 " prot={} markdownSupport={}",Trace::trunc(comment),fileName,lineNr,isBrief,

4733 isAutoBriefOn,isInbody,prot,markdownSupport);

4734 yyscan_t yyscanner = p->yyscanner;

4735 struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;

4736

4737 initParser(yyscanner);

4738 yyextra->guards = guards;

4739 yyextra->langParser = parser;

4740 yyextra->current = curEntry;

4741 yyextra->current->docLine = (lineNr > 1 ? lineNr : 1);

4742 if (comment.isEmpty()) return FALSE; // avoid empty strings

4743 yyextra->inputString = comment;

4744 yyextra->inputString.append(" ");

4745 yyextra->inputPosition = position;

4746 yyextra->lineNr = lineNr;

4747 yyextra->fileName = fileName;

4748 yyextra->protection = prot;

4749 yyextra->needNewEntry = FALSE;

4750 yyextra->xrefKind = XRef_None;

4751 yyextra->xrefAppendFlag = FALSE;

4752 yyextra->insidePre = FALSE;

4753 yyextra->parseMore = FALSE;

4754 yyextra->inBody = isInbody;

4755 yyextra->markdownSupport= markdownSupport;

4756 yyextra->outputXRef.clear();

4757 if (!isBrief && !isAutoBriefOn && !yyextra->current->doc.isEmpty())

4758 { // add newline separator between detailed comment blocks

4759 yyextra->current->doc += '\n';

4760 }

4761 setOutput(yyscanner, isBrief || isAutoBriefOn ? OutputBrief : OutputDoc );

4762 yyextra->briefEndsAtDot = isAutoBriefOn;

4763 yyextra->condCount = 0;

4764 yyextra->sectionLevel = 0;

4765 yyextra->spaceBeforeCmd.clear();

4766 yyextra->spaceBeforeIf.clear();

4767 yyextra->htmlContextStack.clear();

4768

4769 DebugLex debugLex(Debug::Lex_commentscan, __FILE__, !fileName.isEmpty() ? qPrint(fileName): nullptr);

4770 if (!yyextra->current->inbodyDocs.isEmpty() && isInbody) // separate in body fragments

4771 {

4772 char cmd[30];

4773 qsnprintf(cmd,30,"\n\n\\iline %d \\ilinebr ",lineNr);

4774 yyextra->current->inbodyDocs+=cmd;

4775 }

4776

4777 Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\n"

4778 "input=[\n{}]\n",fileName,lineNr,yyextra->inputString

4779 );

4780

4781 commentscanYYrestart( nullptr, yyscanner );

4782 BEGIN( Comment );

4783 commentscanYYlex(yyscanner);

4784 setOutput(yyscanner, OutputDoc );

4785

4786 if (YY_START==OverloadParam) // comment ended with \overload

4787 {

4788 addOutput(yyscanner,getOverloadDocs());

4789 }

4790

4791 if (yyextra->insideParBlock)

4792 {

4793 warn(yyextra->fileName,yyextra->lineNr,

4794 "Documentation block ended while inside a \\parblock. Missing \\endparblock");

4795 }

4796

4797 yyextra->current->doc=stripLeadingAndTrailingEmptyLines(yyextra->current->doc,yyextra->current->docLine);

4798 yyextra->current->brief=stripLeadingAndTrailingEmptyLines(yyextra->current->brief,yyextra->current->docLine);

4799

4800 if (yyextra->current->section.isFileDoc() && yyextra->current->doc.isEmpty())

4801 {

4802 // to allow a comment block with just a @file command.

4803 yyextra->current->doc="\n\n";

4804 }

4805

4806 if (yyextra->current->section.isMemberGrp() &&

4807 yyextra->docGroup.isEmpty()) // @name section but no group started yet

4808 {

4809 yyextra->docGroup.open(yyextra->current,yyextra->fileName,yyextra->lineNr,true);

4810 }

4811

4812 Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\noutput=[\n"

4813 "brief=[line={}\n{}]\ndocs=[line={}\n{}]\ninbody=[line={}\n{}]\n]\n===========\n",

4814 fileName,lineNr,

4815 yyextra->current->briefLine,yyextra->current->brief,

4816 yyextra->current->docLine,yyextra->current->doc,

4817 yyextra->current->inbodyLine,yyextra->current->inbodyDocs

4818 );

4819

4820 checkFormula(yyscanner);

4821 prot = yyextra->protection;

4822

4823 yyextra->docGroup.addDocs(curEntry);

4824

4825 newEntryNeeded = yyextra->needNewEntry;

4826

4827 // if we did not proceed during this call, it does not make

4828 // sense to continue, since we get stuck. See bug 567346 for situations

4829 // were this happens

4830 if (yyextra->parseMore && position==yyextra->inputPosition) yyextra->parseMore=FALSE;

4831

4832 if (!yyextra->parseMore && !yyextra->guards->empty())

4833 {

4834 warn(yyextra->fileName,yyextra->lineNr,"Documentation block ended in the middle of a conditional section!");

4835 }

4836

4837 if (yyextra->parseMore) position=yyextra->inputPosition; else position=0;

4838

4839 lineNr = yyextra->lineNr;

4840 AUTO_TRACE_EXIT("position={} parseMore={} newEntryNeeded={}",

4841 position,yyextra->parseMore,newEntryNeeded);

4842

4843 return yyextra->parseMore;

4844}

References addOutput, AUTO_TRACE, AUTO_TRACE_EXIT, checkFormula, comment, Debug::CommentScan, Entry::docLine, FALSE, getOverloadDocs, initParser, QCString::isEmpty, Debug::Lex_commentscan, OutputBrief, OutputDoc, p, Debug::print, qPrint, qsnprintf, setOutput, stripLeadingAndTrailingEmptyLines, Trace::trunc, warn and XRef_None.

Referenced by generateHtmlForComment and CitationManager::generatePage.

Private Member Attributes

p

std::unique_ptr<Private> CommentScanner::p

Definition at line 120 of file commentscan.h.

120 std::unique_ptr<Private> p;

Referenced by close, CommentScanner, enterCompound, enterFile, initGroupInfo, leaveCompound, leaveFile, open, parseCommentBlock and ~CommentScanner.

---

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

• commentscan.h
• commentscan.l

---

Generated via doxygen2docusaurus by Doxygen 1.14.0.