Added @parblock and @endparblock commands (3b9f4d9c) · Commits · Elphel / doxverilog

doc/commands.doc

+31 −0

Original line number	Diff line number	Diff line
		@@ -85,6 +85,7 @@ documentation:
		\refitem cmdendlink \\endlink
		\refitem cmdendmanonly \\endmanonly
		\refitem cmdendmsc \\endmsc
		\refitem cmdendparblock \\endparblock
		\refitem cmdendrtfonly \\endrtfonly
		\refitem cmdendsecreflist \\endsecreflist
		\refitem cmdendverbatim \\endverbatim
		@@ -136,6 +137,7 @@ documentation:
		\refitem cmdpar \\par
		\refitem cmdparagraph \\paragraph
		\refitem cmdparam \\param
		\refitem cmdparblock \\parblock
		\refitem cmdpost \\post
		\refitem cmdpre \\pre
		\refitem cmdprivate \\private
		@@ -1472,6 +1474,35 @@ void setPosition(double x,double y,double z,double t)
		@param datatype1\|datatype2 $paramname description
		\endverbatim

		<hr>
		\section cmdparblock \\parblock
		\addindex \\parblock
		For commands that expect a single paragraph as argument
		(such as \ref cmdpar "\\par", \ref cmdparam "\\param" and \ref cmdwarning "\\warning"),
		the \ref cmdparblock "\\parblock" command allows to start a
		description that covers multiple paragraphs, which then ends with
		\ref cmdendparblock "\\endparblock".

		Example:
		\verbatim
		/** Example of a param command with a description consisting of two paragraphs
		* \param p
		* \parblock
		* First paragraph of the param description.
		*
		* Second paragraph of the param description.
		* \endparblock
		* Rest of the comment block continues.
		*/
		\endverbatim
		Note that the \\parblock command may also appear directly after
		\\param's first argument.

		<hr>
		\section cmdendparblock \\endparblock
		\addindex \\endparblock
		This ends a block of paragraphs started with \\ref cmdparblock "\\parblock".

		<hr>
		\section cmdtparam \\tparam <template-parameter-name> { description }

src/cmdmapper.cpp

+2 −0

Original line number	Diff line number	Diff line
		@@ -132,6 +132,8 @@ CommandMap cmdMap[] =
		{ "docbookonly", CMD_DBONLY },
		{ "enddocbookonly",CMD_ENDDBONLY },
		{ "endinternal", CMD_ENDINTERNAL },
		{ "parblock", CMD_PARBLOCK },
		{ "endparblock", CMD_ENDPARBLOCK },
		{ 0, 0 },
		};

src/cmdmapper.h

+3 −1

Original line number	Diff line number	Diff line
		@@ -121,7 +121,9 @@ enum CommandType
		CMD_VHDLFLOW = 91,
		CMD_DBONLY = 92,
		CMD_ENDDBONLY = 93,
		CMD_ENDINTERNAL = 94
		CMD_ENDINTERNAL = 94,
		CMD_PARBLOCK = 95,
		CMD_ENDPARBLOCK = 96
		};

		enum HtmlTagType

src/commentscan.l

+41 −3

Original line number	Diff line number	Diff line
		@@ -118,6 +118,8 @@ static bool handleExtends(const QCString &);
		static bool handleCopyDoc(const QCString &);
		static bool handleCopyBrief(const QCString &);
		static bool handleCopyDetails(const QCString &);
		static bool handleParBlock(const QCString &);
		static bool handleEndParBlock(const QCString &);

		typedef bool (*DocCmdFunc)(const QCString &name);

		@@ -170,6 +172,8 @@ static DocCmdMap docCmdMap[] =
		{ "relates", &handleRelated, TRUE },
		{ "relatedalso", &handleRelatedAlso, TRUE },
		{ "relatesalso", &handleRelatedAlso, TRUE },
		{ "parblock", &handleParBlock, TRUE },
		{ "endparblock", &handleEndParBlock, TRUE },
		{ "refitem", &handleRefItem, TRUE },
		{ "cite", &handleCite, FALSE },
		{ "subpage", &handleSubpage, TRUE },
		@@ -421,6 +425,8 @@ static QCString g_copyDocArg;
		static QCString g_guardExpr;
		static int g_roundCount;

		static bool g_insideParBlock;

		//-----------------------------------------------------------------------------

		static QStack<Grouping> g_autoGroupStack;
		@@ -437,6 +443,7 @@ static void initParser()
		g_sectionLabel.resize(0);
		g_sectionTitle.resize(0);
		g_memberGroupHeader.resize(0);
		g_insideParBlock = FALSE;
		}

		//-----------------------------------------------------------------------------
		@@ -1040,7 +1047,7 @@ RCSTAG "$"{ID}":"[^\n$]+"$"
		int i=0;
		while (yytext[i]==' ' \|\| yytext[i]=='\t') i++;
		g_spaceBeforeCmd = QCString(yytext).left(i);
		if (cmdPtr->endsBrief)
		if (cmdPtr->endsBrief && inContext!=OutputXRef)
		{
		briefEndsAtDot=FALSE;
		// this command forces the end of brief description
		@@ -1192,7 +1199,7 @@ RCSTAG "$"{ID}":"[^\n$]+"$"
		if (inContext==OutputXRef)
		{
		// see bug 613024, we need to put the newlines after ending the XRef section.
		setOutput(OutputDoc);
		if (!g_insideParBlock) setOutput(OutputDoc);
		int i;
		for (i=0;i<yyleng;)
		{
		@@ -2389,6 +2396,31 @@ static bool handleXRefItem(const QCString &)
		return FALSE;
		}

		static bool handleParBlock(const QCString &)
		{
		if (g_insideParBlock)
		{
		warn(yyFileName,yyLineNr,
		"found \\parblock command while already in a parblock!");
		}
		addOutput("@parblock");
		g_insideParBlock = TRUE;
		return FALSE;
		}

		static bool handleEndParBlock(const QCString &)
		{
		if (!g_insideParBlock)
		{
		warn(yyFileName,yyLineNr,
		"found \\endparblock command without matching \\parblock!");
		}
		addOutput("@endparblock");
		setOutput(OutputDoc); // to end a parblock inside a xrefitem like context
		g_insideParBlock = FALSE;
		return FALSE;
		}

		static bool handleRelated(const QCString &)
		{
		BEGIN(RelatesParam1);
		@@ -2810,6 +2842,12 @@ bool parseCommentBlock(/* in / ParserInterface parser,
		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())

src/compound.xsd

+7 −0

Original line number	Diff line number	Diff line
		@@ -508,6 +508,7 @@
		<xsd:element name="xrefsect" type="docXRefSectType" />
		<xsd:element name="copydoc" type="docCopyType" />
		<xsd:element name="blockquote" type="docBlockQuoteType" />
		<xsd:element name="parblock" type="docParBlockType" />
		</xsd:choice>
		</xsd:group>

		@@ -707,6 +708,12 @@
		</xsd:sequence>
		</xsd:complexType>

		<xsd:complexType name="docParBlockType">
		<xsd:sequence>
		<xsd:element name="para" type="docParaType" minOccurs="0" maxOccurs="unbounded" />
		</xsd:sequence>
		</xsd:complexType>

		<xsd:complexType name="docCharType">
		<xsd:attribute name="char" type="DoxCharRange"/>
		</xsd:complexType>