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

                               : p(std::make_unique<Private>())
{
  commentscanYYlex_init_extra(&p->extra,&p->yyscanner);
#ifdef FLEX_DEBUG
  commentscanYYset_debug(Debug::isFlagSet(Debug::Lex_commentscan)?1:0,p->yyscanner);
#endif
}

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

◆ ~CommentScanner()

CommentScanner::~CommentScanner ( )

Definition at line 4977 of file commentscan.l.

{
  commentscanYYlex_destroy(p->yyscanner);
}

References p.

Member Function Documentation

◆ addDeprecatedDocs()

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

Definition at line 5211 of file commentscan.l.

{
  static reg::Ex deprecated_re(R"(deprecated\s*(\‍(\s*\"([^\"]*)\"\s*\))?)");
  reg::Match match;
  std::string attr = current->attributes.str();
  if (reg::search(attr,match,deprecated_re))
  {
    DString docs;
    if (match.size()==3) // deprecated attribute with documentation
    {
      Markdown markdown(fileName,line);
      DString rawDoc = match[2].str();
      DString processedDoc = Config_getBool(MARKDOWN_SUPPORT) ? markdown.process(rawDoc,line) : rawDoc;
      std::shared_ptr<Entry> docEntry = std::make_shared<Entry>();
      GuardedSectionStack guards;
      bool newEntryNeeded = false;
      Protection prot = Protection::Public;
      int position=0;
      parseCommentBlock(parser,
                        docEntry.get(),
                        processedDoc,
                        fileName,
                        line,
                        false, // isBrief
                        false, // isAutoBriefOn
                        false, // isInbody
                        prot,
                        position,
                        newEntryNeeded,
                        Config_getBool(MARKDOWN_SUPPORT), // markdownSupport
                        &guards);
      docs = docEntry->doc;
      //printf("rawDoc='%s' processedDoc='%s' docs='%s'\n",qPrint(rawDoc),qPrint(processedDoc),qPrint(docs));
    }
    else // deprecated attribute without documentation
    {
      current->spec.setDeprAttr(true);
    }
    if (!docs.empty() || !current->spec.isDeprDoc()) // attribute has docs
                                                       // or no @deprecated command found in comment yet
    {
      // add new deprecated xref item to the documentation of this entry
      addXRefItemToEntry(current,
                         docs,
                         "deprecated",
                         theTranslator->trDeprecated(),
                         theTranslator->trDeprecatedList(),
                         false,  // append
                         false,  // inBody
                         line);
    }
  }
  else
  {
    //printf("no match in attributes='%s'\n",qPrint(attr));
  }
}

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

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

References p.

◆ enterCompound()

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

Definition at line 5182 of file commentscan.l.

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

References p.

◆ enterFile()

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

Definition at line 5170 of file commentscan.l.

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

References p.

Referenced by generateHtmlForComment().

◆ initGroupInfo()

void CommentScanner::initGroupInfo ( Entry * entry )

Definition at line 5164 of file commentscan.l.

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

References p.

◆ isCommand()

bool CommentScanner::isCommand ( const DString & cmdName )

static

Definition at line 5206 of file commentscan.l.

{
  return (docCmdMap.find(cmdName.str()) != docCmdMap.end());
}

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

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

References p.

◆ leaveFile()

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

Definition at line 5176 of file commentscan.l.

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

References p.

Referenced by generateHtmlForComment().

◆ open()

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

Definition at line 5194 of file commentscan.l.

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

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]	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.
[in,out]	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.
[in,out]	prot	The protection level in which this comment block was found. Commands in the comment block may override this.
[in,out]	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.
[in,out]	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.

Definition at line 4982 of file commentscan.l.

{
  AUTO_TRACE("comment='{}' fileName={} lineNr={} isBrief={} isAutoBriefOn={} inInbody={}"
             " prot={} markdownSupport={}",Trace::trunc(comment),fileName,lineNr,isBrief,
             isAutoBriefOn,isInbody,prot,markdownSupport);
  yyscan_t yyscanner = p->yyscanner;
  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
 
  initParser(yyscanner);
  yyextra->guards = guards;
  yyextra->langParser     = parser;
  yyextra->current        = curEntry;
  yyextra->current->docLine = (lineNr > 1 ? lineNr : 1);
  if (comment.empty()) return false; // avoid empty strings
  yyextra->inputString    = comment;
  yyextra->inputString.append(" ");
  yyextra->inputPosition  = position;
  yyextra->lineNr         = lineNr;
  yyextra->fileName       = fileName;
  yyextra->protection     = prot;
  yyextra->needNewEntry   = false;
  yyextra->xrefKind       = XRef_None;
  yyextra->xrefAppendFlag = false;
  yyextra->insidePre      = false;
  yyextra->parseMore      = false;
  yyextra->inBody         = isInbody;
  yyextra->markdownSupport= markdownSupport;
  yyextra->outputXRef.clear();
  if (!isBrief && !isAutoBriefOn && !yyextra->current->doc.empty())
  { // add newline separator between detailed comment blocks
    yyextra->current->doc += '\n';
  }
  setOutput(yyscanner, isBrief || isAutoBriefOn ? OutputBrief : OutputDoc );
  yyextra->briefEndsAtDot = isAutoBriefOn;
  yyextra->condCount    = 0;
  yyextra->sectionLevel = 0;
  yyextra->spaceBeforeCmd.clear();
  yyextra->spaceBeforeIf.clear();
  yyextra->htmlContextStack.clear();
 
  DebugLex debugLex(Debug::Lex_commentscan, __FILE__, !fileName.empty() ? qPrint(fileName): nullptr);
  if (!yyextra->current->inbodyDocs.empty() && isInbody) // separate in body fragments
  {
    char cmd[30];
    snprintf(cmd,30,"\n\n\\iline %d \\ilinebr ",lineNr);
    yyextra->current->inbodyDocs+=cmd;
  }
 
  Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\n"
               "input=[\n{}]\n",fileName,lineNr,yyextra->inputString
              );
 
  commentscanYYrestart( nullptr, yyscanner );
  BEGIN( Comment );
  commentscanYYlex(yyscanner);
  setOutput(yyscanner, OutputDoc );
 
  if (YY_START==OverloadParam) // comment ended with \overload
  {
    addOutput(yyscanner,theTranslator->trOverloadText());
  }
 
  if (yyextra->insideParBlock)
  {
    warn(yyextra->fileName,yyextra->lineNr,
        "Documentation block ended while inside a \\parblock. Missing \\endparblock");
  }
 
  yyextra->current->doc=stripLeadingAndTrailingEmptyLines(yyextra->current->doc,yyextra->current->docLine);
  yyextra->current->brief=stripLeadingAndTrailingEmptyLines(yyextra->current->brief,yyextra->current->docLine);
 
  if (yyextra->current->section.isFileDoc() && yyextra->current->doc.empty())
  {
    // to allow a comment block with just a @file command.
    yyextra->current->doc="\n\n";
  }
 
  if (yyextra->current->section.isMemberGrp() &&
      yyextra->docGroup.empty()) // @name section but no group started yet
  {
    yyextra->docGroup.open(yyextra->current,yyextra->fileName,yyextra->lineNr,true);
  }
 
  Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: {}:{}\noutput=[\n"
               "brief=[line={}\n{}]\ndocs=[line={}\n{}]\ninbody=[line={}\n{}]\n]\n===========\n",
               fileName,lineNr,
               yyextra->current->briefLine,yyextra->current->brief,
               yyextra->current->docLine,yyextra->current->doc,
               yyextra->current->inbodyLine,yyextra->current->inbodyDocs
              );
 
  checkFormula(yyscanner);
  prot = yyextra->protection;
 
  yyextra->docGroup.addDocs(curEntry);
 
  newEntryNeeded = yyextra->needNewEntry;
 
  // if we did not proceed during this call, it does not make
  // sense to continue, since we get stuck. See bug 567346 for situations
  // were this happens
  if (yyextra->parseMore && position==yyextra->inputPosition) yyextra->parseMore=false;
 
  if (!yyextra->parseMore && !yyextra->guards->empty())
  {
    warn(yyextra->fileName,yyextra->lineNr,"Documentation block ended in the middle of a conditional section!");
  }
 
  if (yyextra->parseMore) position=yyextra->inputPosition; else position=0;
 
  lineNr = yyextra->lineNr;
  AUTO_TRACE_EXIT("position={} parseMore={} newEntryNeeded={}",
      position,yyextra->parseMore,newEntryNeeded);
 
  return yyextra->parseMore;
}