Miscounting of lines in respect to page command

All examples together are a bit big so they are all in the attached file together with the warnings before and after this patch.

When looking at the output we see that a number of lines are off by 1 ore more due to the insertion of extra lines in the code or due to the fact that there is a reference to the start of the documentation of the page and not the line of the page command.

- commentscan.l
  in case of a rule contaiinge {DOCNL} this can be `=n` or `\ilinebr` in the later case this should not be replaced by `\n` as this results in an increase of the line count later on.
  in case of a page like command also register the line of the command as "topline".
- entry.h, entry.cpp
  storage space for the "topline" registering the line of the page like commands.
- doxygen.cpp
  setting and using the "topline"
- markdown.cpp, markdown.h
  don't add a `\n` as this increases the line count but use the `\ilinebr`
  to get correct warnings see to it that when having empty lines at the top of the page and a page is added that the empty lines appear after the page command.
- index.cpp
  using the "topline" instead of the "docLine" to get the correct warning
- pagedef.cpp, pagedef.h
  set and retrieve the "topline" for page like commands.
- util.cpp, util.h
   setting and using the "topline"
   in `addRelatedPage` use the known file name and  line for the warning regarding the section label

- cite.cpp, context.cpp, reflist.cpp
  changed to have good function calls.

1 files changed, 24 insertions, 21 deletions

diff --git a/src/commentscan.l b/src/commentscan.l
index ce495a1..25086f5 100644
--- a/src/commentscan.l
+++ b/src/commentscan.l
@@ -438,6 +438,8 @@ static void handleGuard(yyscan_t yyscanner,const QCString &expr);
 static yy_size_t yyread(yyscan_t yyscanner,char *buf,yy_size_t max_size);
 static void addCite(yyscan_t yyscanner);
 
+#define unputDocnl  for (int i=(int)yyleng-1;i>=0;i--) unput(yytext[i]);
+
 //-----------------------------------------------------------------------------
 
 #undef        YY_INPUT
@@ -872,9 +874,9 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                             yyextra->briefEndsAtDot=FALSE;
                                           }
                                         }
-<Comment>\n                             { // newline
-                                          addOutput(yyscanner,*yytext);
-                                          yyextra->lineNr++;
+<Comment>{DOCNL}                             { // newline
+                                          addOutput(yyscanner,yytext);
+                                          if (*yytext == '\n') yyextra->lineNr++;
                                         }
 <Comment>.                              { // catch-all for anything else
                                           addOutput(yyscanner,*yytext);
@@ -954,7 +956,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                           warn(yyextra->fileName,yyextra->lineNr,
                                                "missing argument after \\enum."
                                               );
-                                          unput('\n');
+                                          unputDocnl;
                                           //addOutput(yyscanner,'\n');
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           BEGIN( Comment );
@@ -977,7 +979,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                                "missing argument after "
                                                "\\namespace."
                                               );
-                                          unput('\n');
+                                          unputDocnl;
                                           //addOutput(yyscanner,'\n');
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           BEGIN( Comment );
@@ -1000,7 +1002,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                                "missing argument after "
                                                "\\package."
                                               );
-                                          unput('\n');
+                                          unputDocnl;
                                           //addOutput(yyscanner,'\n');
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           BEGIN( Comment );
@@ -1038,7 +1040,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                               );
                                           //addOutput(yyscanner,'\n');
                                           //if (*yytext=='\n') yyextra->lineNr++;
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <ClassDocArg1,CategoryDocArg1>.         { // ignore other stuff
@@ -1047,7 +1049,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
 <ClassDocArg2>{DOCNL}                   {
                                           //addOutput(yyscanner,'\n');
                                           //if (*yytext=='\n') yyextra->lineNr++;
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <ClassDocArg2>{FILE}|"<>"               { // second argument; include file
@@ -1071,7 +1073,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                         }
 <ClassDocArg3>{DOCNL}                   {
                                           //if (*yytext=='\n') yyextra->lineNr++;
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <ClassDocArg3>.                         { // ignore other stuff
@@ -1102,7 +1104,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                               );
                                           //addOutput(yyscanner,'\n');
                                           //if (*yytext=='\n') yyextra->lineNr++;
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <GroupDocArg1>.                         { // ignore other stuff
@@ -1125,7 +1127,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                                  "\\defgroup %s", yyextra->current->name.data()
                                                 );
                                           }
-                                          unput('\n');
+                                          unputDocnl;
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
                                           BEGIN( Comment );
@@ -1150,7 +1152,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                                "missing argument after "
                                                "\\page."
                                               );
-                                          unput('\n');
+                                          unputDocnl;
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
                                           BEGIN( Comment );
@@ -1158,7 +1160,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
 <PageDocArg1>.                          { // ignore other stuff
                                         }
 <PageDocArg2>{DOCNL}                    { // second argument; page title
-                                          unput('\n');
+                                          unputDocnl;
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
                                           BEGIN( Comment );
@@ -1192,7 +1194,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
   /* --------- handle arguments of the file/dir/example command ------------ */
 
 <FileDocArg1>{DOCNL}                    { // no file name specified
-                                          unput('\n');
+                                          unputDocnl;
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
                                           BEGIN( Comment );
@@ -1290,7 +1292,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                           warn(yyextra->fileName,yyextra->lineNr,
                                               "Missing argument of '\\%s' command",yyextra->currentCmd.data()
                                               );
-                                          unput('\n');
+                                          unputDocnl;
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
                                           BEGIN( Comment );
@@ -1304,7 +1306,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
 <LineParam>{DOCNL}                      { // end of argument
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <LineParam>{LC}                         { // line continuation
@@ -1668,7 +1670,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
 <NameParam>{DOCNL}                      { // end of argument
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <NameParam>{LC}                         { // line continuation
@@ -1706,7 +1708,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                           }
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <InGroupParam>{LC}                      { // line continuation
@@ -1724,7 +1726,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                           {
                                             //if (*yytext=='\n') yyextra->lineNr++;
                                             //addOutput(yyscanner,'\n');
-                                            unput('\n');
+                                            unputDocnl;
                                             yyextra->langParser->parsePrototype(yyextra->functionProto);
                                             BEGIN( Comment );
                                           }
@@ -1811,7 +1813,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                               );
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <ExtendsParam>.                         { // ignore other stuff
@@ -1848,7 +1850,7 @@ RCSTAG    "$"{ID}":"[^\n$]+"$"
                                               );
                                           //if (*yytext=='\n') yyextra->lineNr++;
                                           //addOutput(yyscanner,'\n');
-                                          unput('\n');
+                                          unputDocnl;
                                           BEGIN( Comment );
                                         }
 <CiteLabel>.                            { // invalid character for cite label
@@ -2783,6 +2785,7 @@ static bool makeStructuralIndicator(yyscan_t yyscanner,Entry::Sections s)
     yyextra->current->section = s;
     yyextra->current->fileName = yyextra->fileName;
     yyextra->current->startLine = yyextra->lineNr;
+    yyextra->current->topLine = yyextra->lineNr;
     return FALSE;
   }
 }