From d5546cff5c82157f2dfddd0e1c4fdeeee8e501dd Mon Sep 17 00:00:00 2001 From: albert-github Date: Sat, 23 Aug 2014 18:09:56 +0200 Subject: Better handling of inline Fortran parameter documentation In case the comment for Fortran arguments is empty or just contains @param [direction] or parts of these. The comment is is not shown and (depending on the configuration settings, a warning is given). Also the detection of inconsistencies between intent attribute and documentation has been improved. --- src/fortranscanner.l | 122 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 80 insertions(+), 42 deletions(-) diff --git a/src/fortranscanner.l b/src/fortranscanner.l index 64a49ca..765f887 100644 --- a/src/fortranscanner.l +++ b/src/fortranscanner.l @@ -2155,79 +2155,117 @@ static void handleCommentBlock(const QCString &doc,bool brief) } //---------------------------------------------------------------------------- - +/// Handle parameter description as defined after the declaration of the parameter static void subrHandleCommentBlock(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 = ""; - if (docBlock.stripWhiteSpace().find("\\param") == 0) + // strip \\param or @param, so we can do some extra checking. We will add it later on again. + if (loc_doc.find("\\param") == 0) { - handleCommentBlock("\n\n"+doc,brief); + loc_doc = loc_doc.right(loc_doc.length()-strlen("\\param")).stripWhiteSpace(); } - else if (docBlock.stripWhiteSpace().find("@param") == 0) + else if (loc_doc.find("@param") == 0) { - handleCommentBlock("\n\n"+doc,brief); + loc_doc = loc_doc.right(loc_doc.length()-strlen("@param")).stripWhiteSpace(); } - else + + // direction as defined with the declaration of the parameter + int dir1 = modifiers[current_root][argName.lower()].direction; + // in description [in] is specified + if (loc_doc.lower().find(directionParam[SymbolModifiers::IN]) == 0) { - int dir1 = modifiers[current_root][argName.lower()].direction; - loc_doc = doc.stripWhiteSpace(); - if (loc_doc.lower().find(directionParam[SymbolModifiers::IN]) == 0) + // check if with the declaration intent(in) or nothing has been specified + if ((directionParam[dir1] == directionParam[SymbolModifiers::NONE_D]) || + (directionParam[dir1] == directionParam[SymbolModifiers::IN])) { - if ((directionParam[dir1] == directionParam[SymbolModifiers::NONE_D]) || - (directionParam[dir1] == directionParam[SymbolModifiers::IN])) + // strip direction + loc_doc = loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::IN])); + // in case of emty documentation or (now) just name, consider it as no documemntation + if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) { - handleCommentBlock(QCString("\n\n@param ") + directionParam[SymbolModifiers::IN] + " " + - argName + " " + loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::IN])),brief); - } - else - { - warn(yyFileName,yyLineNr, "inconsistency between intent attribute and documentation for variable: "+argName); - handleCommentBlock(QCString("\n\n@param ") + directionParam[dir1] + " " + - argName + " " + doc,brief); + // reset current back to the part inside the routine + current=tmp_entry; + return; } + handleCommentBlock(QCString("\n\n@param ") + directionParam[SymbolModifiers::IN] + " " + + argName + " " + loc_doc,brief); } - else if (loc_doc.lower().find(directionParam[SymbolModifiers::OUT]) == 0) + else { - if ((directionParam[dir1] == directionParam[SymbolModifiers::NONE_D]) || - (directionParam[dir1] == directionParam[SymbolModifiers::OUT])) - { - handleCommentBlock(QCString("\n\n@param ") + directionParam[SymbolModifiers::OUT] + " " + - argName + " " + loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::OUT])),brief); - } - else - { - warn(yyFileName,yyLineNr, "inconsistency between intent attribute and documentation for variable: "+argName); - handleCommentBlock(QCString("\n\n@param ") + directionParam[dir1] + " " + - argName + " " + doc,brief); - } + // something different specified, give warning and leave error. + warn(yyFileName,yyLineNr, "Routine: " + current->name + current->args + + " inconsistency between intent attribute and documentation for parameter: " + argName); + handleCommentBlock(QCString("\n\n@param ") + directionParam[dir1] + " " + + argName + " " + loc_doc,brief); } - else if (loc_doc.lower().find(directionParam[SymbolModifiers::INOUT]) == 0) + } + // analogous to the [in] case, here [out] direction specified + else if (loc_doc.lower().find(directionParam[SymbolModifiers::OUT]) == 0) + { + if ((directionParam[dir1] == directionParam[SymbolModifiers::NONE_D]) || + (directionParam[dir1] == directionParam[SymbolModifiers::OUT])) { - if ((directionParam[dir1] == directionParam[SymbolModifiers::NONE_D]) || - (directionParam[dir1] == directionParam[SymbolModifiers::INOUT])) + loc_doc = loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::OUT])); + if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) { - handleCommentBlock(QCString("\n\n@param ") + directionParam[SymbolModifiers::INOUT] + " " + - argName + " " + loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::INOUT])),brief); + current=tmp_entry; + return; } - else + handleCommentBlock(QCString("\n\n@param ") + directionParam[SymbolModifiers::OUT] + " " + + argName + " " + loc_doc,brief); + } + else + { + warn(yyFileName,yyLineNr, "Routine: " + current->name + current->args + + " inconsistency between intent attribute and documentation for parameter: " + argName); + handleCommentBlock(QCString("\n\n@param ") + directionParam[dir1] + " " + + argName + " " + loc_doc,brief); + } + } + // analogous to the [in] case, here [in,out] direction specified + else if (loc_doc.lower().find(directionParam[SymbolModifiers::INOUT]) == 0) + { + if ((directionParam[dir1] == directionParam[SymbolModifiers::NONE_D]) || + (directionParam[dir1] == directionParam[SymbolModifiers::INOUT])) + { + loc_doc = loc_doc.right(loc_doc.length()-strlen(directionParam[SymbolModifiers::INOUT])); + if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) { - warn(yyFileName,yyLineNr, "inconsistency between intent attribute and documentation for variable: "+argName); - handleCommentBlock(QCString("\n\n@param ") + directionParam[dir1] + " " + - argName + " " + doc,brief); + current=tmp_entry; + return; } + handleCommentBlock(QCString("\n\n@param ") + directionParam[SymbolModifiers::INOUT] + " " + + argName + " " + loc_doc,brief); } else { + warn(yyFileName,yyLineNr, "Routine: " + current->name + current->args + + " inconsistency between intent attribute and documentation for parameter: " + argName); handleCommentBlock(QCString("\n\n@param ") + directionParam[dir1] + " " + - argName + " " + doc,brief); + argName + " " + loc_doc,brief); } } + // analogous to the [in] case; here no direction specified + else + { + if (loc_doc.isEmpty() || (loc_doc.lower() == argName.lower())) + { + current=tmp_entry; + return; + } + handleCommentBlock(QCString("\n\n@param ") + directionParam[dir1] + " " + + argName + " " + loc_doc,brief); + } + + // reset current back to the part inside the routine current=tmp_entry; } -- cgit v0.12