commentscan.h File Reference

Interface for the comment block parser. More...

#include "types.h"

Go to the source code of this file.

Functions
bool	parseCommentBlock (ParserInterface *parser, Entry *curEntry, const QCString &comment, const QCString &fileName, int &lineNr, bool isBrief, bool isJavaDocStyle, bool isInbody, Protection &prot, int &position, bool &newEntryNeeded)
void	groupEnterFile (const char *file, int line)
void	groupLeaveFile (const char *file, int line)
void	groupLeaveCompound (const char *file, int line, const char *name)
void	groupEnterCompound (const char *file, int line, const char *name)
void	openGroup (Entry *e, const char *file, int line)
void	closeGroup (Entry *, const char *file, int line, bool foundInline=FALSE)
void	initGroupInfo (Entry *e)

Detailed Description

Interface for the comment block parser.

Definition in file commentscan.h.

Function Documentation

void closeGroup	(	Entry *	,
		const char *	file,
		int	line,
		bool	foundInline = FALSE
	)

Definition at line 8382 of file commentscan.cpp.

{
  //printf("==> closeGroup(name=%s,sec=%x,file=%s,line=%d) g_autoGroupStack=%d\n",
  //    e->name.data(),e->section,fileName,line,g_autoGroupStack.count());
  if (g_memberGroupId!=DOX_NOGROUP) // end of member group
  {
    MemberGroupInfo *info=Doxygen::memGrpInfoDict.find(g_memberGroupId);
    if (info) // known group
    {
      info->doc = g_memberGroupDocs;
      info->docFile = fileName;
      info->docLine = line;
    }
    g_memberGroupId=DOX_NOGROUP;
    g_memberGroupRelates.resize(0);
    g_memberGroupDocs.resize(0);
    if (!foundInline) e->mGrpId=DOX_NOGROUP;
    //printf("new group id=%d\n",g_memberGroupId);
  }
  else if (!g_autoGroupStack.isEmpty()) // end of auto group
  {
    Grouping *grp = g_autoGroupStack.pop();
    // see bug577005: we should not remove the last group for e
    if (!foundInline) e->groups->removeLast();
    //printf("Removing %s e=%p\n",grp->groupname.data(),e);
    delete grp;
    if (!foundInline) initGroupInfo(e);
  }
}

void groupEnterCompound	(	const char *	file,
		int	line,
		const char *	name
	)

Definition at line 8299 of file commentscan.cpp.

{
  if (g_memberGroupId!=DOX_NOGROUP)
  {
    warn(fileName,line,"try to put compound %s inside a member group\n",name);
  }
  g_memberGroupId=DOX_NOGROUP;
  g_memberGroupRelates.resize(0);
  g_memberGroupDocs.resize(0);
  g_compoundName = name;
  int i = g_compoundName.find('(');
  if (i!=-1) 
  {
    g_compoundName=g_compoundName.left(i); // strip category (Obj-C)
  }
  if (g_compoundName.isEmpty())
  {
    g_compoundName=fileName;
  }
  //printf("groupEnterCompound(%s)\n",name);
}

void groupEnterFile	(	const char *	file,
		int	line
	)

Definition at line 8274 of file commentscan.cpp.

{
  g_autoGroupStack.setAutoDelete(TRUE);
  g_autoGroupStack.clear();
  g_memberGroupId = DOX_NOGROUP;
  g_memberGroupDocs.resize(0);
  g_memberGroupRelates.resize(0);
  g_compoundName=fileName;
}

void groupLeaveCompound	(	const char *	file,
		int	line,
		const char *	name
	)

Definition at line 8321 of file commentscan.cpp.

{
  //printf("groupLeaveCompound(%s)\n",name);
  //if (g_memberGroupId!=DOX_NOGROUP)
  //{
  //  warn(fileName,line,"end of compound %s while inside a member group\n",name);
  //}
  g_memberGroupId=DOX_NOGROUP;
  g_memberGroupRelates.resize(0);
  g_memberGroupDocs.resize(0);
  g_compoundName.resize(0);
}

void groupLeaveFile	(	const char *	file,
		int	line
	)

Definition at line 8284 of file commentscan.cpp.

{
  //if (g_memberGroupId!=DOX_NOGROUP)
  //{
  //  warn(fileName,line,"end of file while inside a member group\n");
  //}
  g_memberGroupId=DOX_NOGROUP;
  g_memberGroupRelates.resize(0);
  g_memberGroupDocs.resize(0);
  if (!g_autoGroupStack.isEmpty())
  {
    warn(fileName,line,"end of file while inside a group\n");
  }
}

void initGroupInfo

(

Entry *

e

)

Definition at line 8412 of file commentscan.cpp.

{
  //printf("==> initGroup(id=%d,related=%s,e=%p)\n",g_memberGroupId,
  //       g_memberGroupRelates.data(),e);
  e->mGrpId     = g_memberGroupId;
  e->relates    = g_memberGroupRelates;
  if (!g_autoGroupStack.isEmpty())
  {
    //printf("Appending group %s to %s: count=%d entry=%p\n",
    //  g_autoGroupStack.top()->groupname.data(),
    //  e->name.data(),e->groups->count(),e);
    e->groups->append(new Grouping(*g_autoGroupStack.top()));
  }
}

void openGroup	(	Entry *	e,
		const char *	file,
		int	line
	)

Definition at line 8354 of file commentscan.cpp.

{
  //printf("==> openGroup(name=%s,sec=%x) g_autoGroupStack=%d\n",
  //    e->name.data(),e->section,g_autoGroupStack.count());
  if (e->section==Entry::GROUPDOC_SEC) // auto group
  {
    g_autoGroupStack.push(new Grouping(e->name,e->groupingPri()));
  }
  else // start of a member group
  {
    //printf("    membergroup id=%d %s\n",g_memberGroupId,g_memberGroupHeader.data());
    if (g_memberGroupId==DOX_NOGROUP) // no group started yet
    {
      static int curGroupId=0;

      MemberGroupInfo *info = new MemberGroupInfo;
      info->header = g_memberGroupHeader.stripWhiteSpace();
      info->compoundName = g_compoundName;
      g_memberGroupId = findExistingGroup(curGroupId,info);
      //printf("    use membergroup %d\n",g_memberGroupId);
      Doxygen::memGrpInfoDict.insert(g_memberGroupId,info);

      g_memberGroupRelates = e->relates;
      e->mGrpId = g_memberGroupId;
    }
  }
}

bool parseCommentBlock	(	ParserInterface *	parser,
		Entry *	curEntry,
		const QCString &	comment,
		const QCString &	fileName,
		int &	lineNr,
		bool	isBrief,
		bool	isJavaDocStyle,
		bool	isInbody,
		Protection &	prot,
		int &	position,
		bool &	newEntryNeeded
	)

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.

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 8149 of file commentscan.cpp.

{
  //printf("parseCommentBlock() isBrief=%d isAutoBriefOn=%d lineNr=%d\n",
  //    isBrief,isAutoBriefOn,lineNr);

  initParser();
  guards.setAutoDelete(TRUE);
  guards.clear();
  langParser     = parser;
  current        = curEntry;
  if (comment.isEmpty()) return FALSE; // avoid empty strings
  inputString    = comment;
  inputString.append(" ");
  inputPosition  = position;
  yyLineNr       = lineNr;
  yyFileName     = fileName;
  protection     = prot;
  needNewEntry   = FALSE;
  xrefKind       = XRef_None;
  xrefAppendFlag = FALSE;
  insidePre      = FALSE;
  parseMore      = FALSE;
  inBody         = isInbody;
  outputXRef.resize(0);
  setOutput( isBrief || isAutoBriefOn ? OutputBrief : OutputDoc );
  briefEndsAtDot = isAutoBriefOn;
  g_condCount    = 0;
  g_sectionLevel = 0;
  g_spaceBeforeCmd.resize(0);
  g_spaceBeforeIf.resize(0);

  printlex(commentscanYY_flex_debug, TRUE, __FILE__, fileName ? fileName.data(): NULL);
  if (!current->inbodyDocs.isEmpty() && isInbody) // separate in body fragments
  {
    current->inbodyDocs+="\n\n";
  }

  Debug::print(Debug::CommentScan,0,"-----------\nCommentScanner: %s:%d\n"
               "input=[\n%s]\n",qPrint(fileName),lineNr,qPrint(comment)
              );
  
  commentscanYYrestart( commentscanYYin );
  BEGIN( Comment );
  commentscanYYlex();
  setOutput( OutputDoc );

  if (YY_START==OverloadParam) // comment ended with \overload
  {
    addOutput(getOverloadDocs());
  }

  if (!guards.isEmpty())
  {
    warn(yyFileName,yyLineNr,"Documentation block ended in the middle of a conditional section!");
  }

  if (g_insideParBlock)
  {
    warn(yyFileName,yyLineNr,
        "Documentation block ended while inside a \\parblock. Missing \\endparblock");
  }

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

  if (current->section==Entry::FILEDOC_SEC && current->doc.isEmpty())
  {
    // to allow a comment block with just a @file command.
    current->doc="\n\n";
  }

  if (current->section==Entry::MEMBERGRP_SEC &&
      g_memberGroupId==DOX_NOGROUP) // @name section but no group started yet
  {
    openGroup(current,yyFileName,yyLineNr);
  }

  if (Doxygen::markdownSupport)
  {
    current->brief      = processMarkdown(fileName,lineNr,current,current->brief);
    current->doc        = processMarkdown(fileName,lineNr,current,current->doc);
    current->inbodyDocs = processMarkdown(fileName,lineNr,current,current->inbodyDocs);
  }

  Debug::print(Debug::CommentScan,0,
               "brief=[line=%d\n%s]\ndocs=[line=%d\n%s]\ninbody=[line=%d\n%s]\n===========\n",
               current->briefLine,qPrint(current->brief),
               current->docLine,qPrint(current->doc),
               current->inbodyLine,qPrint(current->inbodyDocs)
              );
  
  checkFormula();
  prot = protection;
  
  groupAddDocs(curEntry);

  newEntryNeeded = 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 (parseMore && position==inputPosition) parseMore=FALSE;

  if (parseMore) position=inputPosition; else position=0;

  lineNr = yyLineNr;
  //printf("position=%d parseMore=%d newEntryNeeded=%d\n",
  //  position,parseMore,newEntryNeeded);

  printlex(commentscanYY_flex_debug, FALSE, __FILE__, fileName ? fileName.data(): NULL);
  return parseMore;
}