From 478207365d7f09f0e676a76f654502c084806e4e Mon Sep 17 00:00:00 2001 From: albert-github Date: Thu, 1 Jan 2015 13:11:23 +0100 Subject: Documentation HTML Header, Footer, and Stylesheet changes Adjusted text to better reflect current situation. --- doc/customize.doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/customize.doc b/doc/customize.doc index 46b1d8b..c7359c1 100644 --- a/doc/customize.doc +++ b/doc/customize.doc @@ -117,9 +117,9 @@ This will create 3 files: You should edit these files and then reference them from the config file. - \ref cfg_html_header "HTML_HEADER" = \c header.html - \ref cfg_html_footer "HTML_FOOTER" = \c footer.html -- \ref cfg_html_stylesheet "HTML_STYLESHEET" = \c customdoxygen.css ←obsolete +- \ref cfg_html_extra_stylesheet "HTML_EXTRA_STYLESHEET" = \c my_customdoxygen.css -\note it is not longer recommended to use HTML_STYLESHEET this way, +\note it is not longer recommended to use \ref cfg_html_stylesheet "HTML_STYLESHEET", as it make it difficult to upgrade to a newer version of doxygen. Use \ref cfg_html_extra_stylesheet "HTML_EXTRA_STYLESHEET" instead. -- cgit v0.12 From 7569f42d95332a5948e9d35e94e88d56d11634a9 Mon Sep 17 00:00:00 2001 From: albert-github Date: Thu, 1 Jan 2015 13:22:22 +0100 Subject: Help message regarding layout file The name of the layout file can be omitted. --- src/doxygen.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doxygen.cpp b/src/doxygen.cpp index e127b8e..b1b7c08 100644 --- a/src/doxygen.cpp +++ b/src/doxygen.cpp @@ -9962,7 +9962,7 @@ static void usage(const char *name) msg(" If - is used for configName doxygen will read from standard input.\n\n"); msg("4) Use doxygen to generate a template file controlling the layout of the\n"); msg(" generated documentation:\n"); - msg(" %s -l layoutFileName.xml\n\n",name); + msg(" %s -l [layoutFileName.xml]\n\n",name); msg("5) Use doxygen to generate a template style sheet file for RTF, HTML or Latex.\n"); msg(" RTF: %s -w rtf styleSheetFile\n",name); msg(" HTML: %s -w html headerFile footerFile styleSheetFile [configFile]\n",name); -- cgit v0.12 From 25a90990662449808c5ba58c243a7835d13ba750 Mon Sep 17 00:00:00 2001 From: albert-github Date: Thu, 1 Jan 2015 13:27:30 +0100 Subject: Fortran FUNCTION source code In case of a Fortran FUNCTION there was a difference between the handling of the source code lines for functions with and without the RESULT clause. This has been made uniform. --- src/fortranscanner.l | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/fortranscanner.l b/src/fortranscanner.l index 4875606..4967095 100644 --- a/src/fortranscanner.l +++ b/src/fortranscanner.l @@ -982,6 +982,8 @@ private { result=result.stripWhiteSpace(); addSubprogram(result); BEGIN(Subprog); + current->bodyLine = yyLineNr + lineCountPrepass + 1; // we have to be at the line after the definition and we have to take continuation lines into account. + current->startLine = yyLineNr; } ^{BS}({PREFIX}{BS_})?{SUBPROG}{BS_} { -- cgit v0.12 From 21f9e87db8085fb1b5e0a9a9a25dee159b3fd324 Mon Sep 17 00:00:00 2001 From: albert-github Date: Thu, 1 Jan 2015 15:28:08 +0100 Subject: Documenting RESULT variable of Fortran FUNCTION Fortran functions can specify the return value by means of a variable in the RESULT attribute. Analogous to argument variables (@param) it is now possible to document also the return / RESULT variable (@returns). --- src/fortranscanner.l | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/src/fortranscanner.l b/src/fortranscanner.l index 4875606..e28158f 100644 --- a/src/fortranscanner.l +++ b/src/fortranscanner.l @@ -72,7 +72,7 @@ #define YY_NEVER_INTERACTIVE 1 #define YY_NO_INPUT 1 -enum ScanVar { V_IGNORE, V_VARIABLE, V_PARAMETER}; +enum ScanVar { V_IGNORE, V_VARIABLE, V_PARAMETER, V_RESULT}; enum InterfaceType { IF_NONE, IF_SPECIFIC, IF_GENERIC, IF_ABSTRACT }; // {{{ ----- Helper structs ----- @@ -202,6 +202,7 @@ static int yyread(char *buf,int max_size); static void startCommentBlock(bool); static void handleCommentBlock(const QCString &doc,bool brief); static void subrHandleCommentBlock(const QCString &doc,bool brief); +static void subrHandleCommentBlockResult(const QCString &doc,bool brief); static void addCurrentEntry(int case_insens); static void addModule(const char *name, bool isModule=FALSE); static void addSubprogram(const char *text); @@ -844,6 +845,7 @@ private { QCString rght; if (strt != -1) { + v_type = V_RESULT; lft = ""; rght = ""; if (strt != 0) lft = current_root->type.left(strt).stripWhiteSpace(); @@ -864,6 +866,10 @@ private { } if (current_root->type.length() > 0) current_root->type += " "; current_root->type += "function"; + if (!docBlock.isNull()) + { + subrHandleCommentBlockResult(docBlock,TRUE); + } } else { @@ -1105,6 +1111,10 @@ private { { subrHandleCommentBlock(docBlock,TRUE); } + else if (v_type == V_RESULT) + { + subrHandleCommentBlockResult(docBlock,TRUE); + } yy_pop_state(); docBlock.resize(0); } @@ -2322,6 +2332,47 @@ static void subrHandleCommentBlock(const QCString &doc,bool brief) // reset current back to the part inside the routine current=tmp_entry; } +//---------------------------------------------------------------------------- +/// Handle result description as defined after the declaration of the parameter +static void subrHandleCommentBlockResult(const QCString &doc,bool brief) +{ + QCString loc_doc; + loc_doc = doc.stripWhiteSpace(); + + Entry *tmp_entry = current; + current = subrCurrent.getFirst(); // temporarily switch to the entry of the subroutine / function + + // Still in the specification section so no inbodyDocs yet, but parameter documentation + current->inbodyDocs = ""; + + // strip \\param or @param, so we can do some extra checking. We will add it later on again. + if (loc_doc.find("\\returns") == 0) + { + loc_doc = loc_doc.right(loc_doc.length()-strlen("\\returns")).stripWhiteSpace(); + } + else if (loc_doc.find("@returns") == 0) + { + loc_doc = loc_doc.right(loc_doc.length()-strlen("@returns")).stripWhiteSpace(); + } + if (loc_doc.find("\\return") == 0) + { + loc_doc = loc_doc.right(loc_doc.length()-strlen("\\return")).stripWhiteSpace(); + } + else if (loc_doc.find("@return") == 0) + { + loc_doc = loc_doc.right(loc_doc.length()-strlen("@return")).stripWhiteSpace(); + } + + if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) + { + current=tmp_entry; + return; + } + handleCommentBlock(QCString("\n\n@returns ") + loc_doc,brief); + + // reset current back to the part inside the routine + current=tmp_entry; +} //---------------------------------------------------------------------------- #if 0 -- cgit v0.12 From 6720a714461b9454c7cdbae7ceff7eb735feeb3b Mon Sep 17 00:00:00 2001 From: albert-github Date: Thu, 1 Jan 2015 16:20:46 +0100 Subject: Suggestion to use stripPrefix has been implemented for RESULT. For consistency also implemented for arguments. --- src/fortranscanner.l | 39 ++++++++++++++------------------------- 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/src/fortranscanner.l b/src/fortranscanner.l index e28158f..f628c26 100644 --- a/src/fortranscanner.l +++ b/src/fortranscanner.l @@ -2232,14 +2232,10 @@ static void subrHandleCommentBlock(const QCString &doc,bool brief) current->inbodyDocs = ""; // strip \\param or @param, so we can do some extra checking. We will add it later on again. - if (loc_doc.find("\\param") == 0) - { - loc_doc = loc_doc.right(loc_doc.length()-strlen("\\param")).stripWhiteSpace(); - } - else if (loc_doc.find("@param") == 0) - { - loc_doc = loc_doc.right(loc_doc.length()-strlen("@param")).stripWhiteSpace(); - } + if (!loc_doc.stripPrefix("\\param") && + !loc_doc.stripPrefix("@param") + ); // Do nothing work has been done by stripPrefix + loc_doc.stripWhiteSpace(); // direction as defined with the declaration of the parameter int dir1 = modifiers[current_root][argName.lower()].direction; @@ -2252,6 +2248,7 @@ static void subrHandleCommentBlock(const QCString &doc,bool brief) { // strip direction loc_doc = loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::IN])); + loc_doc.stripWhiteSpace(); // in case of emty documentation or (now) just name, consider it as no documemntation if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) { @@ -2278,6 +2275,7 @@ static void subrHandleCommentBlock(const QCString &doc,bool brief) (directionParam[dir1] == directionParam[SymbolModifiers::OUT])) { loc_doc = loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::OUT])); + loc_doc.stripWhiteSpace(); if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) { current=tmp_entry; @@ -2301,6 +2299,7 @@ static void subrHandleCommentBlock(const QCString &doc,bool brief) (directionParam[dir1] == directionParam[SymbolModifiers::INOUT])) { loc_doc = loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::INOUT])); + loc_doc.stripWhiteSpace(); if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) { current=tmp_entry; @@ -2345,23 +2344,13 @@ static void subrHandleCommentBlockResult(const QCString &doc,bool brief) // Still in the specification section so no inbodyDocs yet, but parameter documentation current->inbodyDocs = ""; - // strip \\param or @param, so we can do some extra checking. We will add it later on again. - if (loc_doc.find("\\returns") == 0) - { - loc_doc = loc_doc.right(loc_doc.length()-strlen("\\returns")).stripWhiteSpace(); - } - else if (loc_doc.find("@returns") == 0) - { - loc_doc = loc_doc.right(loc_doc.length()-strlen("@returns")).stripWhiteSpace(); - } - if (loc_doc.find("\\return") == 0) - { - loc_doc = loc_doc.right(loc_doc.length()-strlen("\\return")).stripWhiteSpace(); - } - else if (loc_doc.find("@return") == 0) - { - loc_doc = loc_doc.right(loc_doc.length()-strlen("@return")).stripWhiteSpace(); - } + // strip \\returns or @returns. We will add it later on again. + if (!loc_doc.stripPrefix("\\returns") && + !loc_doc.stripPrefix("\\return") && + !loc_doc.stripPrefix("@returns") && + !loc_doc.stripPrefix("@return") + ); // Do nothing work has been done by stripPrefix + loc_doc.stripWhiteSpace(); if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) { -- cgit v0.12