bug 683051 Template parameter cannot be commented inline

Adding possibilities for inline documentation of template arguments with classes and functions

Author: albert-github

src/arguments.cpp

@@ -23,3 +23,10 @@ bool ArgumentList::hasDocumentation() const
   return std::any_of(begin(),end(),[](const Argument &a){ return a.hasDocumentation(); });
 }
 
+/*! the template argument list is documented if one of its
+ *  template arguments is documented
+ */
+bool ArgumentList::hasTemplateDocumentation() const
+{
+  return std::any_of(begin(),end(),[](const Argument &a){ return a.hasTemplateDocumentation(); });
+}

src/arguments.h

@@ -33,6 +33,11 @@ struct Argument
     return !name.isEmpty() && !docs.isEmpty();
   }
 
+  bool hasTemplateDocumentation() const
+  {
+    return (!name.isEmpty() || !type.isEmpty()) && !docs.isEmpty();
+  }
+
   QCString attrib;   /*!< Argument's attribute (IDL only) */
   QCString type;     /*!< Argument's type */
   QCString canType;  /*!< Cached value of canonical type (after type resolution). Empty initially. */
@@ -65,6 +70,8 @@ class ArgumentList
 
     /*! Does any argument of this list have documentation? */
     bool hasDocumentation() const;
+    /*! Does any template argument of this list have documentation? */
+    bool hasTemplateDocumentation() const;
     /*! Does this list have zero or more parameters */
     bool hasParameters() const
     {

src/classdef.cpp

@@ -1615,6 +1615,16 @@ void ClassDefImpl::writeDetailedDocumentationBody(OutputList &ol) const
   // write type constraints
   writeTypeConstraints(ol,this,m_typeConstraints);
 
+  ol.generateDoc(
+        docFile(),docLine(),
+        this,
+        nullptr,         // memberDef
+        inlineTemplateArgListToDoc(m_tempArgs),    // docStr
+        TRUE,         // indexWords
+        FALSE,        // isExample
+        QCString(),FALSE,FALSE,Config_getBool(MARKDOWN_SUPPORT)
+        );
+
   // write examples
   if (hasExamples())
   {
@@ -1633,7 +1643,7 @@ bool ClassDefImpl::hasDetailedDescription() const
   bool repeatBrief = Config_getBool(REPEAT_BRIEF);
   bool sourceBrowser = Config_getBool(SOURCE_BROWSER);
   return ((!briefDescription().isEmpty() && repeatBrief) ||
-          !documentation().isEmpty() ||
+          (!documentation().isEmpty() || m_tempArgs.hasTemplateDocumentation()) ||
           (sourceBrowser && getStartBodyLine()!=-1 && getBodyDef()));
 }
 
@@ -3556,15 +3566,15 @@ bool ClassDefImpl::isLinkableInProject() const
     //      !isAnonymous(),
     //      m_prot,
     //      !m_isLocal   || extractLocal,
-    //      hasDocumentation() || !hideUndoc,
+    //      hasDocumentation() ||  m_tempArgs.hasTemplateDocumentation() || !hideUndoc,
     //      !m_isStatic  || extractStatic,
     //      !isReference());
     return
       !isArtificial() && !isHidden() &&            /* not hidden */
       !isAnonymous() &&                            /* not anonymous */
       protectionLevelVisible(m_prot)      && /* private/internal */
       (!m_isLocal      || extractLocal)   && /* local */
-      (hasDocumentation()    || !hideUndoc)     && /* documented */
+      (hasDocumentation() || m_tempArgs.hasTemplateDocumentation() || !hideUndoc)     && /* documented */
       (!m_isStatic     || extractStatic)  && /* static */
       !isReference();                              /* not an external reference */
   }

src/memberdef.cpp

@@ -2692,7 +2692,10 @@ bool MemberDefImpl::hasDetailedDescription() const
            // has one or more documented arguments
            (m_templateMaster ?
             m_templateMaster->argumentList().hasDocumentation() :
-            m_defArgList.hasDocumentation());
+            m_defArgList.hasDocumentation()) ||
+           (m_templateMaster ?
+            m_templateMaster->templateArguments().hasTemplateDocumentation() :
+            m_tArgList.hasTemplateDocumentation());
 
     // generate function                  guard
     // ==================                 =======
@@ -3874,6 +3877,19 @@ void MemberDefImpl::writeDocumentation(const MemberList *ml,
         QCString(),FALSE,FALSE,Config_getBool(MARKDOWN_SUPPORT)
         );
 
+  const ArgumentList &docTemplateArgList = m_templateMaster ?
+                                   m_templateMaster->templateArguments() :
+                                   m_tArgList;
+  ol.generateDoc(
+        docFile(),docLine(),
+        scopedContainer,
+        this,         // memberDef
+        inlineTemplateArgListToDoc(docTemplateArgList),    // docStr
+        TRUE,         // indexWords
+        FALSE,        // isExample
+        QCString(),FALSE,FALSE,Config_getBool(MARKDOWN_SUPPORT)
+        );
+
   _writeEnumValues(ol,scopedContainer,cfname,ciname,cname);
   _writeReimplements(ol);
   _writeReimplementedBy(ol);
@@ -4300,7 +4316,7 @@ bool MemberDefImpl::hasDocumentation() const
 {
   return DefinitionMixin::hasDocumentation() ||
          (m_mtype==MemberType::Enumeration && m_docEnumValues) ||  // has enum values
-         (m_defArgList.hasDocumentation());   // has doc arguments
+         (m_defArgList.hasDocumentation()|| m_tArgList.hasTemplateDocumentation());   // has doc (template) arguments
 }
 
 

src/scanner.l

@@ -5034,6 +5034,7 @@ NONLopt [^\n]*
                                           yyextra->fullArgString+=*yytext;
                                           //printf("end template list '%s'\n",qPrint(*yyextra->copyArgString));
                                           *yyextra->currentArgumentList = *stringToArgumentList(yyextra->language, yyextra->fullArgString);
+                                          handleParametersCommentBlocks(yyscanner,yyextra->current->tArgLists.back());
                                           BEGIN( yyextra->currentArgumentContext );
                                         }
 <CopyArgRound>"("                       {

src/util.cpp

@@ -1171,6 +1171,33 @@ QCString inlineArgListToDoc(const ArgumentList &al)
   return paramDocs;
 }
 
+QCString inlineTemplateArgListToDoc(const ArgumentList &al)
+{
+  QCString paramDocs;
+  if (al.hasTemplateDocumentation())
+  {
+    for (const Argument &a : al)
+    {
+      if (!a.docs.isEmpty())
+      {
+        if (!a.name.isEmpty())
+        {
+          paramDocs+=" \\ilinebr @tparam "+a.name+" "+a.docs;
+        }
+        else if (!a.type.isEmpty())
+        {
+          QCString type = a.type;
+          type.stripPrefix("class ");
+          type.stripPrefix("typename ");
+          type = type.stripWhiteSpace();
+          paramDocs+=" \\ilinebr @tparam "+type+" "+a.docs;
+        }
+      }
+    }
+  }
+  return paramDocs;
+}
+
 QCString argListToString(const ArgumentList &al,bool useCanonicalType,bool showDefVals)
 {
   QCString result;

src/util.h

@@ -215,6 +215,7 @@ inline bool isIdJS(int c)
 QCString removeRedundantWhiteSpace(const QCString &s);
 
 QCString inlineArgListToDoc(const ArgumentList &al);
+QCString inlineTemplateArgListToDoc(const ArgumentList &al);
 
 QCString argListToString(const ArgumentList &al,bool useCanonicalType=FALSE,bool showDefVals=TRUE);
 

src/xmlgen.cpp

@@ -59,6 +59,12 @@
 // debug inside output
 //#define XML_DB(x) QCString __t;__t.sprintf x;m_t << __t
 
+static void writeXMLDocBlock(TextStream &t,
+                      const QCString &fileName,
+                      int lineNr,
+                      const Definition *scope,
+                      const MemberDef * md,
+                      const QCString &text);
 //------------------
 
 inline void writeXMLString(TextStream &t,const QCString &s)
@@ -403,6 +409,20 @@ static void writeTemplateArgumentList(TextStream &t,
         linkifyText(TextGeneratorXMLImpl(t),scope,fileScope,nullptr,a.typeConstraint);
         t << "</typeconstraint>\n";
       }
+      if (a.hasTemplateDocumentation())
+      {
+        t << indentStr << "    <briefdescription>\n";
+        t << indentStr << "      ";
+        if (scope)
+        {
+          writeXMLDocBlock(t,scope->briefFile(),scope->briefLine(),scope,nullptr,a.docs);
+        }
+        else
+        {
+          writeXMLDocBlock(t,fileScope->briefFile(),fileScope->briefLine(),fileScope,nullptr,a.docs);
+        }
+        t << indentStr << "    </briefdescription>\n";
+      }
       t << indentStr << "  </param>\n";
     }
     t << indentStr << "</templateparamlist>\n";