Merge branch 'master' of github.com:doxygen/doxygen

Author: Dimitri van Heesch

doc/commands.doc

@@ -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

src/cmdmapper.cpp

@@ -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 },

src/cmdmapper.h

@@ -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

src/docparser.cpp

@@ -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;

src/docparser.h

@@ -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,

src/fortranscanner.l

@@ -322,6 +322,12 @@ SCOPENAME ({ID}{BS}"::"{BS})*
 
  /*-----------------------------------------------------------------------------------*/
 
+<Prepass>^{BS}[&]*{BS}!.*\n             { /* skip lines with just comment. Note code was in free format or has been converted to it */
+                                          lineCountPrepass ++;
+                                        }
+<Prepass>^{BS}\n                        { /* skip empty lines */
+                                          lineCountPrepass ++;
+                                        }
 <*>^.*\n                                { // prepass: look for line continuations
   					  functionLine = FALSE;
 
@@ -1422,6 +1428,7 @@ static const char* prepassFixedForm(const char* contents)
   bool inSingle=FALSE;
   bool inDouble=FALSE;
   bool inBackslash=FALSE;
+  bool fullCommentLine=TRUE;
   int newContentsSize = strlen(contents)+3; // \000, \n (when necessary) and one spare character (to avoid reallocation)
   char* newContents = (char*)malloc(newContentsSize);
 
@@ -1435,8 +1442,17 @@ static const char* prepassFixedForm(const char* contents)
     char c = contents[i];
     switch(c) {
       case '\n':
-        prevLineLength=column;
-        prevLineAmpOrExclIndex=getAmpOrExclAtTheEnd(&contents[i-prevLineLength+1], prevLineLength,prevQuote);
+        if (!fullCommentLine)
+        {
+          prevLineLength=column;
+          prevLineAmpOrExclIndex=getAmpOrExclAtTheEnd(&contents[i-prevLineLength+1], prevLineLength,prevQuote);
+          if (prevLineAmpOrExclIndex == -1) prevLineAmpOrExclIndex = column - 1;
+        }
+        else
+        {
+          prevLineLength+=column;
+        }
+        fullCommentLine=TRUE;
         column=0;
 	emptyLabel=TRUE;
         commented=FALSE;
@@ -1463,7 +1479,8 @@ static const char* prepassFixedForm(const char* contents)
       case '\\':
         if ((column <= fixedCommentAfter) && (column!=6) && !commented)
 	{
-          // we have some special cases in respect to strings and exscaped string characters
+          // we have some special cases in respect to strings and escaped string characters
+          fullCommentLine=FALSE;
 	  newContents[j]=c;
           if (c == '\\')
           {
@@ -1512,13 +1529,15 @@ static const char* prepassFixedForm(const char* contents)
           }
 	  else
           {
+            if (!commented) fullCommentLine=FALSE;
 	    newContents[j]=c;
           }
 	  break;
 	}
         // fallthrough
       default:
         if(column==6 && emptyLabel) { // continuation
+          if (!commented) fullCommentLine=FALSE;
           if (c != '0') { // 0 not allowed as continuation character, see f95 standard paragraph 3.3.2.3
             newContents[j]=' ';
 
@@ -1532,6 +1551,7 @@ static const char* prepassFixedForm(const char* contents)
 	  } else {
 	    newContents[j]=c; // , just handle like space
           }
+          prevLineLength=0;
 	} else if ((column > fixedCommentAfter) && !commented) {
           // first non commented non blank character after position fixedCommentAfter
           if (c != '!') {
@@ -1542,6 +1562,7 @@ static const char* prepassFixedForm(const char* contents)
 	  newContents[j]=c;
           commented = TRUE;
 	} else {
+          if (!commented) fullCommentLine=FALSE;
 	  newContents[j]=c;
 	  emptyLabel=FALSE;
 	}
@@ -2491,7 +2512,11 @@ static void parseMain(const char *fileName,const char *fileBuf,Entry *rt, Fortra
       //printf("---strlen=%d\n", strlen(fileBuf));
       //clock_t start=clock();
 
+      //printf("Input fixed form string:\n%s\n", fileBuf);
+      //printf("===========================\n");
       inputString = prepassFixedForm(fileBuf);
+      //printf("Resulting free form string:\n%s\n", inputString);
+      //printf("===========================\n");
 
       //clock_t end=clock();
       //printf("CPU time used=%f\n", ((double) (end-start))/CLOCKS_PER_SEC);

src/latexdocvisitor.cpp

@@ -431,7 +431,14 @@ void LatexDocVisitor::visit(DocInclude *inc)
                                            inc->text(),
                                            langExt,
                                            inc->isExample(),
-                                           inc->exampleFile(), &fd);
+                                           inc->exampleFile(),
+                                           &fd,   // fileDef,
+                                           -1,    // start line
+                                           -1,    // end line
+                                           FALSE, // inline fragment
+                                           0,     // memberDef
+                                           TRUE   // show line numbers
+					  );
          m_t << "\\end{DoxyCodeInclude}" << endl;
       }
       break;    
@@ -440,7 +447,14 @@ void LatexDocVisitor::visit(DocInclude *inc)
       Doxygen::parserManager->getParser(inc->extension())
                             ->parseCode(m_ci,inc->context(),
                                         inc->text(),langExt,inc->isExample(),
-                                        inc->exampleFile());
+                                        inc->exampleFile(),
+                                        0,     // fileDef
+                                        -1,    // startLine
+                                        -1,    // endLine
+                                        TRUE,  // inlineFragment
+                                        0,     // memberDef
+                                        FALSE
+			  		);
       m_t << "\\end{DoxyCodeInclude}\n";
       break;
     case DocInclude::DontInclude: