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 4788 of file commentscan.l.

4788 : p(std::make_unique<Private>())
4789{
4790 commentscanYYlex_init_extra(&p->extra,&p->yyscanner);
4791#ifdef FLEX_DEBUG
4792 commentscanYYset_debug(Debug::isFlagSet(Debug::Lex_commentscan)?1:0,p->yyscanner);
4793#endif
4794}
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 4796 of file commentscan.l.

4797{
4798 commentscanYYlex_destroy(p->yyscanner);
4799}

References p.

Member Function Documentation

◆ close()

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

Definition at line 5019 of file commentscan.l.

5020{
5021 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5022 yyextra->docGroup.close(e,fileName,lineNr,foundInline,implicit);
5023}

References p.

◆ enterCompound()

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

Definition at line 5001 of file commentscan.l.

5002{
5003 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5004 yyextra->docGroup.enterCompound(fileName,lineNr,name);
5005}

References p.

◆ enterFile()

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

Definition at line 4989 of file commentscan.l.

4990{
4991 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4992 yyextra->docGroup.enterFile(fileName,lineNr);
4993}

References p.

Referenced by generateHtmlForComment().

◆ initGroupInfo()

void CommentScanner::initGroupInfo ( Entry * entry)

Definition at line 4983 of file commentscan.l.

4984{
4985 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4986 yyextra->docGroup.initGroupInfo(entry);
4987}

References p.

◆ leaveCompound()

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

Definition at line 5007 of file commentscan.l.

5008{
5009 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5010 yyextra->docGroup.leaveCompound(fileName,lineNr,name);
5011}

References p.

◆ leaveFile()

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

Definition at line 4995 of file commentscan.l.

4996{
4997 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
4998 yyextra->docGroup.leaveFile(fileName,lineNr);
4999}

References p.

Referenced by generateHtmlForComment().

◆ open()

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

Definition at line 5013 of file commentscan.l.

5014{
5015 struct yyguts_t *yyg = (struct yyguts_t*)p->yyscanner;
5016 yyextra->docGroup.open(e,fileName,lineNr,implicit);
5017}

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 4801 of file commentscan.l.

4815{
4816 AUTO_TRACE("comment='{}' fileName={} lineNr={} isBrief={} isAutoBriefOn={} inInbody={}"
4817 " prot={} markdownSupport={}",Trace::trunc(comment),fileName,lineNr,isBrief,
4818 isAutoBriefOn,isInbody,prot,markdownSupport);
4819 yyscan_t yyscanner = p->yyscanner;
4820 struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
4821
4822 initParser(yyscanner);
4823 yyextra->guards = guards;
4824 yyextra->langParser = parser;
4825 yyextra->current = curEntry;
4826 yyextra->current->docLine = (lineNr > 1 ? lineNr : 1);
4827 if (comment.isEmpty()) return FALSE; // avoid empty strings
4828 yyextra->inputString = comment;
4829 yyextra->inputString.append(" ");
4830 yyextra->inputPosition = position;
4831 yyextra->lineNr = lineNr;
4832 yyextra->fileName = fileName;
4833 yyextra->protection = prot;
4834 yyextra->needNewEntry = FALSE;
4835 yyextra->xrefKind = XRef_None;
4836 yyextra->xrefAppendFlag = FALSE;
4837 yyextra->insidePre = FALSE;
4838 yyextra->parseMore = FALSE;
4839 yyextra->inBody = isInbody;
4840 yyextra->markdownSupport= markdownSupport;
4841 yyextra->outputXRef.clear();
4842 if (!isBrief && !isAutoBriefOn && !yyextra->current->doc.isEmpty())
4843 { // add newline separator between detailed comment blocks
4844 yyextra->current->doc += '\n';
4845 }
4846 setOutput(yyscanner, isBrief || isAutoBriefOn ? OutputBrief : OutputDoc );
4847 yyextra->briefEndsAtDot = isAutoBriefOn;
4848 yyextra->condCount = 0;
4849 yyextra->sectionLevel = 0;
4850 yyextra->spaceBeforeCmd.clear();
4851 yyextra->spaceBeforeIf.clear();
4852 yyextra->htmlContextStack.clear();
4853
4854 DebugLex debugLex(Debug::Lex_commentscan, __FILE__, !fileName.isEmpty() ? qPrint(fileName): nullptr);
4855 if (!yyextra->current->inbodyDocs.isEmpty() && isInbody) // separate in body fragments
4856 {
4857 char cmd[30];
4858 qsnprintf(cmd,30,"\n\n\\iline %d \\ilinebr ",lineNr);
4859 yyextra->current->inbodyDocs+=cmd;
4860 }
4861
4862 Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\n"
4863 "input=[\n{}]\n",fileName,lineNr,yyextra->inputString
4864 );
4865
4866 commentscanYYrestart( nullptr, yyscanner );
4867 BEGIN( Comment );
4868 commentscanYYlex(yyscanner);
4869 setOutput(yyscanner, OutputDoc );
4870
4871 if (YY_START==OverloadParam) // comment ended with \overload
4872 {
4873 addOutput(yyscanner,getOverloadDocs());
4874 }
4875
4876 if (yyextra->insideParBlock)
4877 {
4878 warn(yyextra->fileName,yyextra->lineNr,
4879 "Documentation block ended while inside a \\parblock. Missing \\endparblock");
4880 }
4881
4882 yyextra->current->doc=stripLeadingAndTrailingEmptyLines(yyextra->current->doc,yyextra->current->docLine);
4883 yyextra->current->brief=stripLeadingAndTrailingEmptyLines(yyextra->current->brief,yyextra->current->docLine);
4884
4885 if (yyextra->current->section.isFileDoc() && yyextra->current->doc.isEmpty())
4886 {
4887 // to allow a comment block with just a @file command.
4888 yyextra->current->doc="\n\n";
4889 }
4890
4891 if (yyextra->current->section.isMemberGrp() &&
4892 yyextra->docGroup.isEmpty()) // @name section but no group started yet
4893 {
4894 yyextra->docGroup.open(yyextra->current,yyextra->fileName,yyextra->lineNr,true);
4895 }
4896
4897 Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\noutput=[\n"
4898 "brief=[line={}\n{}]\ndocs=[line={}\n{}]\ninbody=[line={}\n{}]\n]\n===========\n",
4899 fileName,lineNr,
4900 yyextra->current->briefLine,yyextra->current->brief,
4901 yyextra->current->docLine,yyextra->current->doc,
4902 yyextra->current->inbodyLine,yyextra->current->inbodyDocs
4903 );
4904
4905 checkFormula(yyscanner);
4906 prot = yyextra->protection;
4907
4908 yyextra->docGroup.addDocs(curEntry);
4909
4910 newEntryNeeded = yyextra->needNewEntry;
4911
4912 // if we did not proceed during this call, it does not make
4913 // sense to continue, since we get stuck. See bug 567346 for situations
4914 // were this happens
4915 if (yyextra->parseMore && position==yyextra->inputPosition) yyextra->parseMore=FALSE;
4916
4917 if (!yyextra->parseMore && !yyextra->guards->empty())
4918 {
4919 warn(yyextra->fileName,yyextra->lineNr,"Documentation block ended in the middle of a conditional section!");
4920 }
4921
4922 if (yyextra->parseMore) position=yyextra->inputPosition; else position=0;
4923
4924 lineNr = yyextra->lineNr;
4925 AUTO_TRACE_EXIT("position={} parseMore={} newEntryNeeded={}",
4926 position,yyextra->parseMore,newEntryNeeded);
4927
4928 return yyextra->parseMore;
4929}
@ 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:4926
QCString getOverloadDocs()
Definition util.cpp:4010
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: