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

std::unique_ptr< Privatep

Detailed Description

Definition at line 53 of file commentscan.h.

Constructor & Destructor Documentation

◆ CommentScanner()

CommentScanner::CommentScanner ( )

Definition at line 4713 of file commentscan.l.

4713 : p(std::make_unique<Private>())
4714{
4715 commentscanYYlex_init_extra(&p->extra,&p->yyscanner);
4716#ifdef FLEX_DEBUG
4717 commentscanYYset_debug(Debug::isFlagSet(Debug::Lex_commentscan)?1:0,p->yyscanner);
4718#endif
4719}
std::unique_ptr< Private > p
@ Lex_commentscan
Definition debug.h:54
static bool isFlagSet(const DebugMask mask)
Definition debug.cpp:132

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

◆ ~CommentScanner()

CommentScanner::~CommentScanner ( )

Definition at line 4721 of file commentscan.l.

4722{
4723 commentscanYYlex_destroy(p->yyscanner);
4724}

References p.

Member Function Documentation

◆ close()

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

Definition at line 4944 of file commentscan.l.

4945{
4946 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4947 yyextra->docGroup.close(e,fileName,lineNr,foundInline,implicit);
4948}

References p.

◆ enterCompound()

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

Definition at line 4926 of file commentscan.l.

4927{
4928 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4929 yyextra->docGroup.enterCompound(fileName,lineNr,name);
4930}

References p.

◆ enterFile()

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

Definition at line 4914 of file commentscan.l.

4915{
4916 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4917 yyextra->docGroup.enterFile(fileName,lineNr);
4918}

References p.

Referenced by generateHtmlForComment().

◆ initGroupInfo()

void CommentScanner::initGroupInfo ( Entry * entry)

Definition at line 4908 of file commentscan.l.

4909{
4910 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4911 yyextra->docGroup.initGroupInfo(entry);
4912}

References p.

◆ leaveCompound()

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

Definition at line 4932 of file commentscan.l.

4933{
4934 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4935 yyextra->docGroup.leaveCompound(fileName,lineNr,name);
4936}

References p.

◆ leaveFile()

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

Definition at line 4920 of file commentscan.l.

4921{
4922 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4923 yyextra->docGroup.leaveFile(fileName,lineNr);
4924}

References p.

Referenced by generateHtmlForComment().

◆ open()

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

Definition at line 4938 of file commentscan.l.

4939{
4940 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4941 yyextra->docGroup.open(e,fileName,lineNr,implicit);
4942}

References 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]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 4726 of file commentscan.l.

4740{
4741 AUTO_TRACE("comment='{}' fileName={} lineNr={} isBrief={} isAutoBriefOn={} inInbody={}"
4742 " prot={} markdownSupport={}",Trace::trunc(comment),fileName,lineNr,isBrief,
4743 isAutoBriefOn,isInbody,prot,markdownSupport);
4744 yyscan_t yyscanner = p->yyscanner;
4745 struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
4746
4747 initParser(yyscanner);
4748 yyextra->guards = guards;
4749 yyextra->langParser = parser;
4750 yyextra->current = curEntry;
4751 yyextra->current->docLine = (lineNr > 1 ? lineNr : 1);
4752 if (comment.isEmpty()) return FALSE; // avoid empty strings
4753 yyextra->inputString = comment;
4754 yyextra->inputString.append(" ");
4755 yyextra->inputPosition = position;
4756 yyextra->lineNr = lineNr;
4757 yyextra->fileName = fileName;
4758 yyextra->protection = prot;
4759 yyextra->needNewEntry = FALSE;
4760 yyextra->xrefKind = XRef_None;
4761 yyextra->xrefAppendFlag = FALSE;
4762 yyextra->insidePre = FALSE;
4763 yyextra->parseMore = FALSE;
4764 yyextra->inBody = isInbody;
4765 yyextra->markdownSupport= markdownSupport;
4766 yyextra->outputXRef.clear();
4767 if (!isBrief && !isAutoBriefOn && !yyextra->current->doc.isEmpty())
4768 { // add newline separator between detailed comment blocks
4769 yyextra->current->doc += '\n';
4770 }
4771 setOutput(yyscanner, isBrief || isAutoBriefOn ? OutputBrief : OutputDoc );
4772 yyextra->briefEndsAtDot = isAutoBriefOn;
4773 yyextra->condCount = 0;
4774 yyextra->sectionLevel = 0;
4775 yyextra->spaceBeforeCmd.clear();
4776 yyextra->spaceBeforeIf.clear();
4777 yyextra->htmlContextStack.clear();
4778
4779 DebugLex debugLex(Debug::Lex_commentscan, __FILE__, !fileName.isEmpty() ? qPrint(fileName): nullptr);
4780 if (!yyextra->current->inbodyDocs.isEmpty() && isInbody) // separate in body fragments
4781 {
4782 char cmd[30];
4783 qsnprintf(cmd,30,"\n\n\\iline %d \\ilinebr ",lineNr);
4784 yyextra->current->inbodyDocs+=cmd;
4785 }
4786
4787 Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\n"
4788 "input=[\n{}]\n",fileName,lineNr,yyextra->inputString
4789 );
4790
4791 commentscanYYrestart( nullptr, yyscanner );
4792 BEGIN( Comment );
4793 commentscanYYlex(yyscanner);
4794 setOutput(yyscanner, OutputDoc );
4795
4796 if (YY_START==OverloadParam) // comment ended with \overload
4797 {
4798 addOutput(yyscanner,getOverloadDocs());
4799 }
4800
4801 if (yyextra->insideParBlock)
4802 {
4803 warn(yyextra->fileName,yyextra->lineNr,
4804 "Documentation block ended while inside a \\parblock. Missing \\endparblock");
4805 }
4806
4807 yyextra->current->doc=stripLeadingAndTrailingEmptyLines(yyextra->current->doc,yyextra->current->docLine);
4808 yyextra->current->brief=stripLeadingAndTrailingEmptyLines(yyextra->current->brief,yyextra->current->docLine);
4809
4810 if (yyextra->current->section.isFileDoc() && yyextra->current->doc.isEmpty())
4811 {
4812 // to allow a comment block with just a @file command.
4813 yyextra->current->doc="\n\n";
4814 }
4815
4816 if (yyextra->current->section.isMemberGrp() &&
4817 yyextra->docGroup.isEmpty()) // @name section but no group started yet
4818 {
4819 yyextra->docGroup.open(yyextra->current,yyextra->fileName,yyextra->lineNr,true);
4820 }
4821
4822 Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\noutput=[\n"
4823 "brief=[line={}\n{}]\ndocs=[line={}\n{}]\ninbody=[line={}\n{}]\n]\n===========\n",
4824 fileName,lineNr,
4825 yyextra->current->briefLine,yyextra->current->brief,
4826 yyextra->current->docLine,yyextra->current->doc,
4827 yyextra->current->inbodyLine,yyextra->current->inbodyDocs
4828 );
4829
4830 checkFormula(yyscanner);
4831 prot = yyextra->protection;
4832
4833 yyextra->docGroup.addDocs(curEntry);
4834
4835 newEntryNeeded = yyextra->needNewEntry;
4836
4837 // if we did not proceed during this call, it does not make
4838 // sense to continue, since we get stuck. See bug 567346 for situations
4839 // were this happens
4840 if (yyextra->parseMore && position==yyextra->inputPosition) yyextra->parseMore=FALSE;
4841
4842 if (!yyextra->parseMore && !yyextra->guards->empty())
4843 {
4844 warn(yyextra->fileName,yyextra->lineNr,"Documentation block ended in the middle of a conditional section!");
4845 }
4846
4847 if (yyextra->parseMore) position=yyextra->inputPosition; else position=0;
4848
4849 lineNr = yyextra->lineNr;
4850 AUTO_TRACE_EXIT("position={} parseMore={} newEntryNeeded={}",
4851 position,yyextra->parseMore,newEntryNeeded);
4852
4853 return yyextra->parseMore;
4854}
@ CommentScan
Definition debug.h:32
static void print(DebugMask mask, int prio, fmt::format_string< Args... > fmt, Args &&... args)
Definition debug.h:76
int docLine
line number at which the documentation was found
Definition entry.h:201
bool isEmpty() const
Returns TRUE iff the string is empty.
Definition qcstring.h:163
void clear()
Definition qcstring.h:182
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:46
#define AUTO_TRACE_EXIT(...)
Definition docnode.cpp:48
#define warn(file, line, fmt,...)
Definition message.h:97
QCString trunc(const QCString &s, size_t numChars=15)
Definition trace.h:56
#define qsnprintf
Definition qcstring.h:49
const char * qPrint(const char *s)
Definition qcstring.h:687
#define FALSE
Definition qcstring.h:34
QCString stripLeadingAndTrailingEmptyLines(const QCString &s, int &docLine)
Special version of QCString::stripWhiteSpace() that only strips completely blank lines.
Definition util.cpp:5543
QCString getOverloadDocs()
Definition util.cpp:4605
const char * comment

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

Member Data Documentation

◆ p

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

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