Permalink
Browse files

Introducing commands includedoc and snippetdoc

Purpose to have the possibility to have repeating texts not repeated in the comments.
The commands include and snippet introduce code blocks whilst the commands includedoc and snippetdoc inclode the text as is and it will be parsed by doxygen.
  • Loading branch information...
albert-github committed Aug 21, 2016
1 parent b24d9db commit ba848363081c44c9aa9e91b193054983f562e90c
Showing with 110 additions and 17 deletions.
  1. +40 −4 doc/commands.doc
  2. +2 −0 src/cmdmapper.cpp
  3. +3 −1 src/cmdmapper.h
  4. +39 −11 src/docparser.cpp
  5. +1 −1 src/docparser.h
  6. +24 −0 src/util.cpp
  7. +1 −0 src/util.h
@@ -115,6 +115,7 @@ documentation:
\refitem cmdimage \\image
\refitem cmdimplements \\implements
\refitem cmdinclude \\include
\refitem cmdincludedoc \\includedoc
\refitem cmdincludelineno \\includelineno
\refitem cmdingroup \\ingroup
\refitem cmdinternal \\internal
@@ -177,6 +178,7 @@ documentation:
\refitem cmdskip \\skip
\refitem cmdskipline \\skipline
\refitem cmdsnippet \\snippet
\refitem cmdsnippetdoc \\snippetdoc
\refitem cmdstartuml \\startuml
\refitem cmdstruct \\struct
\refitem cmdsubpage \\subpage
@@ -2171,8 +2173,8 @@ Commands for displaying examples
\note Doxygen's special commands do not work inside blocks of code.
It is allowed to nest C-style comments inside a code block though.
\sa sections \ref cmdexample "\\example", \ref cmddontinclude "\\dontinclude", and
\ref cmdverbatim "\\verbatim".
\sa sections \ref cmdexample "\\example", \ref cmddontinclude "\\dontinclude",
\ref cmdverbatim "\\verbatim" and \ref cmdincludedoc "\\includedoc".
<hr>
\section cmdincludelineno \\includelineno <file-name>
@@ -2183,6 +2185,22 @@ Commands for displaying examples
\sa section \ref cmdinclude "\\include".
<hr>
\section cmdincludedoc \\includedoc <file-name>
\addindex \\includedoc
This command works the same way as \ref cmdinclude "\\include", but it will include
the content of the file as if it were at the place where this command is called.
The result is that the content is parsed by doxygen and placed in the documentation.
\note Some commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with
this command due to the moment of parsing.
\note The included documentation should not have comment signs in it as the will appear
in the documentation as well.
\sa section \ref cmdinclude "\\include".
<hr>
\section cmdline \\line ( pattern )
@@ -2285,6 +2303,23 @@ Commands for displaying examples
see section \ref cmddontinclude "\\dontinclude" for an alternative way
to include fragments of a source file that does not require markers.
\sa section \ref cmdsnippetdoc "\\snippetdoc".
<hr>
\section cmdsnippetdoc \\snippetdoc <file-name> ( block_id )
\addindex \\snippetdoc
This command works the same way as \ref cmdsnippet "\\snippet", but it will include
the content of the file between the `block-id`s as if it were at the place where this command is called.
The result is that the content is parsed by doxygen and placed in the documentation.
\note Some commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with
this command due to the moment of parsing.
\note The included documentation should not have comment signs in it as the will appear
in the documentation as well.
\sa section \ref cmdsnippet "\\snippet" and \ref cmdincludedoc "\\includedoc".
<hr>
\section cmduntil \\until ( pattern )
@@ -3177,8 +3212,9 @@ class Receiver
\c \\verbatim command or the parser will get confused!
\sa sections \ref cmdcode "\\code",
\ref cmdendverbatim "\\endverbatim", and
\ref cmdverbinclude "\\verbinclude".
\ref cmdendverbatim "\\endverbatim",
\ref cmdverbinclude "\\verbinclude", and
\ref cmdverbincludedooc "\\verbincludedooc".
<hr>
\section cmdxmlonly \\xmlonly
@@ -88,6 +88,7 @@ CommandMap cmdMap[] =
{ "secreflist", CMD_SECREFLIST },
{ "section", CMD_SECTION },
{ "snippet", CMD_SNIPPET },
{ "snippetdoc", CMD_SNIPPETDOC },
{ "subpage", CMD_SUBPAGE },
{ "subsection", CMD_SUBSECTION },
{ "subsubsection", CMD_SUBSUBSECTION },
@@ -130,6 +131,7 @@ CommandMap cmdMap[] =
{ "manonly", CMD_MANONLY },
{ "endmanonly", CMD_ENDMANONLY },
{ "includelineno", CMD_INCWITHLINES },
{ "includedoc", CMD_INCLUDEDOC },
{ "inheritdoc", CMD_INHERITDOC },
{ "mscfile", CMD_MSCFILE },
{ "rtfonly", CMD_RTFONLY },
@@ -133,7 +133,9 @@ enum CommandType
CMD_SETSCOPE = 103,
CMD_PUNT = 104,
CMD_PLUS = 105,
CMD_MINUS = 106
CMD_MINUS = 106,
CMD_INCLUDEDOC = 107,
CMD_SNIPPETDOC = 108
};
enum HtmlTagType
@@ -123,6 +123,7 @@ struct DocParserContext
QStack<DocStyleChange> initialStyleStack;
QList<Definition> copyStack;
QCString fileName;
int lineNo;
QCString relPath;
bool hasParamCommand;
@@ -144,7 +145,6 @@ struct DocParserContext
static QStack<DocParserContext> g_parserStack;
//---------------------------------------------------------------------------
static void docParserPushContext(bool saveParamInfo=TRUE)
{
//QCString indent;
@@ -163,6 +163,7 @@ static void docParserPushContext(bool saveParamInfo=TRUE)
ctx->initialStyleStack = g_initialStyleStack;
ctx->copyStack = g_copyStack;
ctx->fileName = g_fileName;
ctx->lineNo = doctokenizerYYlineno;
ctx->relPath = g_relPath;
if (saveParamInfo)
@@ -201,6 +202,7 @@ static void docParserPopContext(bool keepParamInfo=FALSE)
g_initialStyleStack = ctx->initialStyleStack;
g_copyStack = ctx->copyStack;
g_fileName = ctx->fileName;
doctokenizerYYlineno = ctx->lineNo;
g_relPath = ctx->relPath;
if (!keepParamInfo)
@@ -5140,7 +5142,6 @@ void DocPara::handleRef(const QCString &cmdName)
doctokenizerYYsetStatePara();
}
void DocPara::handleInclude(const QCString &cmdName,DocInclude::Type t)
{
DBG(("handleInclude(%s)\n",qPrint(cmdName)));
@@ -5168,7 +5169,7 @@ void DocPara::handleInclude(const QCString &cmdName,DocInclude::Type t)
}
QCString fileName = g_token->name;
QCString blockId;
if (t==DocInclude::Snippet)
if (t==DocInclude::Snippet || t==DocInclude::SnippetDoc)
{
if (fileName == "this") fileName=g_fileName;
doctokenizerYYsetStateSnippet();
@@ -5182,9 +5183,31 @@ void DocPara::handleInclude(const QCString &cmdName,DocInclude::Type t)
}
blockId = "["+g_token->name+"]";
}
DocInclude *inc = new DocInclude(this,fileName,g_context,t,g_isExample,g_exampleName,blockId);
m_children.append(inc);
inc->parse();
// This is the only place to handle the \includedoc and \snippetdoc commands,
// as the content is included here as if it is really here.
if (t==DocInclude::IncludeDoc || t==DocInclude::SnippetDoc)
{
QCString inc_text;
int inc_line = 1;
readTextFileByName(fileName,inc_text);
if (t==DocInclude::SnippetDoc)
{
inc_line = lineBlock(inc_text, blockId);
inc_text = extractBlock(inc_text, blockId);
}
docParserPushContext();
g_fileName = fileName;
doctokenizerYYlineno=inc_line;
internalValidatingParseDoc(this,m_children,inc_text);
docParserPopContext();
}
else
{
DocInclude *inc = new DocInclude(this,fileName,g_context,t,g_isExample,g_exampleName,blockId);
m_children.append(inc);
inc->parse();
}
}
void DocPara::handleSection(const QCString &cmdName)
@@ -5419,15 +5442,15 @@ int DocPara::handleCommand(const QCString &cmdName)
break;
case CMD_LI:
{
DocSimpleList *sl=new DocSimpleList(this);
m_children.append(sl);
DocSimpleList *sl=new DocSimpleList(this);
m_children.append(sl);
retval = sl->parse();
}
break;
case CMD_SECTION:
{
handleSection(cmdName);
retval = RetVal_Section;
retval = RetVal_Section;
}
break;
case CMD_SUBSECTION:
@@ -5673,6 +5696,12 @@ int DocPara::handleCommand(const QCString &cmdName)
case CMD_SNIPPET:
handleInclude(cmdName,DocInclude::Snippet);
break;
case CMD_INCLUDEDOC:
handleInclude(cmdName,DocInclude::IncludeDoc);
break;
case CMD_SNIPPETDOC:
handleInclude(cmdName,DocInclude::SnippetDoc);
break;
case CMD_SKIP:
handleIncludeOperator(cmdName,DocIncOperator::Skip);
break;
@@ -6160,8 +6189,7 @@ int DocPara::handleHtmlStartTag(const QCString &tagName,const HtmlAttribList &ta
case XML_INHERITDOC:
handleInheritDoc();
break;
default:
default:
// we should not get here!
ASSERT(0);
break;
@@ -483,7 +483,7 @@ class DocVerbatim : public DocNode
class DocInclude : public DocNode
{
public:
enum Type { Include, DontInclude, VerbInclude, HtmlInclude, LatexInclude, IncWithLines, Snippet };
enum Type { Include, DontInclude, VerbInclude, HtmlInclude, LatexInclude, IncWithLines, Snippet , IncludeDoc, SnippetDoc};
DocInclude(DocNode *parent,const QCString &file,
const QCString context, Type t,
bool isExample,const QCString exampleFile,
@@ -8085,6 +8085,7 @@ bool copyFile(const QCString &src,const QCString &dest)
/** Returns the section of text, in between a pair of markers.
* Full lines are returned, excluding the lines on which the markers appear.
* \sa routine lineBlock
*/
QCString extractBlock(const QCString text,const QCString marker)
{
@@ -8128,6 +8129,29 @@ QCString extractBlock(const QCString text,const QCString marker)
return l2>l1 ? text.mid(l1,l2-l1) : QCString();
}
/** Returns the line number of the line following the line with the marker.
* \sa routine extractBlock
*/
int lineBlock(const QCString text,const QCString marker)
{
int result = 1;
int p=0,i;
bool found=FALSE;
// find the character positions of the first marker
int m1 = text.find(marker);
if (m1==-1) return result;
// find start line positions for the markers
while (!found && (i=text.find('\n',p))!=-1)
{
found = (p<=m1 && m1<i); // found the line with the start marker
p=i+1;
result++;
}
return result;
}
/** Returns a string representation of \a lang. */
QCString langToString(SrcLangExt lang)
{
@@ -445,6 +445,7 @@ QCString replaceColorMarkers(const char *str);
bool copyFile(const QCString &src,const QCString &dest);
QCString extractBlock(const QCString text,const QCString marker);
int lineBlock(const QCString text,const QCString marker);
QCString correctURL(const QCString &url,const QCString &relPath);

0 comments on commit ba84836

Please sign in to comment.