bug 512677 New command specifying an empty comment

A new command `\trivial` is introduced signaling that the entity is "trivial" and does not need to be documented.
Advantage is that the entity will appear in the documentation without using a setting like `EXTRACT_ALL`

Author: albert-github

addon/doxmlparser/doxmlparser/compound.py

@@ -1378,7 +1378,7 @@ class compounddefType(GeneratedsSuper):
     __hash__ = GeneratedsSuper.__hash__
     subclass = None
     superclass = None
-    def __init__(self, id=None, kind=None, language=None, prot=None, final=None, inline=None, sealed=None, abstract=None, compoundname=None, title=None, basecompoundref=None, derivedcompoundref=None, includes=None, includedby=None, incdepgraph=None, invincdepgraph=None, innermodule=None, innerdir=None, innerfile=None, innerclass=None, innerconcept=None, innernamespace=None, innerpage=None, innergroup=None, qualifier=None, templateparamlist=None, sectiondef=None, tableofcontents=None, requiresclause=None, initializer=None, briefdescription=None, detaileddescription=None, exports=None, inheritancegraph=None, collaborationgraph=None, programlisting=None, location=None, listofallmembers=None, gds_collector_=None, **kwargs_):
+    def __init__(self, id=None, kind=None, trivial=None, language=None, prot=None, final=None, inline=None, sealed=None, abstract=None, compoundname=None, title=None, basecompoundref=None, derivedcompoundref=None, includes=None, includedby=None, incdepgraph=None, invincdepgraph=None, innermodule=None, innerdir=None, innerfile=None, innerclass=None, innerconcept=None, innernamespace=None, innerpage=None, innergroup=None, qualifier=None, templateparamlist=None, sectiondef=None, tableofcontents=None, requiresclause=None, initializer=None, briefdescription=None, detaileddescription=None, exports=None, inheritancegraph=None, collaborationgraph=None, programlisting=None, location=None, listofallmembers=None, gds_collector_=None, **kwargs_):
         self.gds_collector_ = gds_collector_
         self.gds_elementtree_node_ = None
         self.original_tagname_ = None
@@ -1388,6 +1388,8 @@ def __init__(self, id=None, kind=None, language=None, prot=None, final=None, inl
         self.id_nsprefix_ = None
         self.kind = _cast(None, kind)
         self.kind_nsprefix_ = None
+        self.trivial = _cast(None, trivial)
+        self.trivial_nsprefix_ = None
         self.language = _cast(None, language)
         self.language_nsprefix_ = None
         self.prot = _cast(None, prot)
@@ -1729,6 +1731,10 @@ def get_kind(self):
         return self.kind
     def set_kind(self, kind):
         self.kind = kind
+    def get_trivial(self):
+        return self.trivial
+    def set_trivial(self, trivial):
+        self.trivial = trivial
     def get_language(self):
         return self.language
     def set_language(self, language):
@@ -1766,44 +1772,44 @@ def validate_DoxCompoundKind(self, value):
                 lineno = self.gds_get_node_lineno_()
                 self.gds_collector_.add_message('Value "%(value)s"%(lineno)s does not match xsd enumeration restriction on DoxCompoundKind' % {"value" : encode_str_2_3(value), "lineno": lineno} )
                 result = False
-    def validate_DoxLanguage(self, value):
-        # Validate type DoxLanguage, a restriction on xsd:string.
+    def validate_DoxBool(self, value):
+        # Validate type DoxBool, a restriction on xsd:string.
         if value is not None and Validate_simpletypes_ and self.gds_collector_ is not None:
             if not isinstance(value, str):
                 lineno = self.gds_get_node_lineno_()
                 self.gds_collector_.add_message('Value "%(value)s"%(lineno)s is not of the correct base simple type (str)' % {"value": value, "lineno": lineno, })
                 return False
             value = value
-            enumerations = ['Unknown', 'IDL', 'Java', 'C#', 'D', 'PHP', 'Objective-C', 'C++', 'JavaScript', 'Python', 'Fortran', 'VHDL', 'XML', 'SQL', 'Markdown', 'Slice', 'Lex']
+            enumerations = ['yes', 'no']
             if value not in enumerations:
                 lineno = self.gds_get_node_lineno_()
-                self.gds_collector_.add_message('Value "%(value)s"%(lineno)s does not match xsd enumeration restriction on DoxLanguage' % {"value" : encode_str_2_3(value), "lineno": lineno} )
+                self.gds_collector_.add_message('Value "%(value)s"%(lineno)s does not match xsd enumeration restriction on DoxBool' % {"value" : encode_str_2_3(value), "lineno": lineno} )
                 result = False
-    def validate_DoxProtectionKind(self, value):
-        # Validate type DoxProtectionKind, a restriction on xsd:string.
+    def validate_DoxLanguage(self, value):
+        # Validate type DoxLanguage, a restriction on xsd:string.
         if value is not None and Validate_simpletypes_ and self.gds_collector_ is not None:
             if not isinstance(value, str):
                 lineno = self.gds_get_node_lineno_()
                 self.gds_collector_.add_message('Value "%(value)s"%(lineno)s is not of the correct base simple type (str)' % {"value": value, "lineno": lineno, })
                 return False
             value = value
-            enumerations = ['public', 'protected', 'private', 'package']
+            enumerations = ['Unknown', 'IDL', 'Java', 'C#', 'D', 'PHP', 'Objective-C', 'C++', 'JavaScript', 'Python', 'Fortran', 'VHDL', 'XML', 'SQL', 'Markdown', 'Slice', 'Lex']
             if value not in enumerations:
                 lineno = self.gds_get_node_lineno_()
-                self.gds_collector_.add_message('Value "%(value)s"%(lineno)s does not match xsd enumeration restriction on DoxProtectionKind' % {"value" : encode_str_2_3(value), "lineno": lineno} )
+                self.gds_collector_.add_message('Value "%(value)s"%(lineno)s does not match xsd enumeration restriction on DoxLanguage' % {"value" : encode_str_2_3(value), "lineno": lineno} )
                 result = False
-    def validate_DoxBool(self, value):
-        # Validate type DoxBool, a restriction on xsd:string.
+    def validate_DoxProtectionKind(self, value):
+        # Validate type DoxProtectionKind, a restriction on xsd:string.
         if value is not None and Validate_simpletypes_ and self.gds_collector_ is not None:
             if not isinstance(value, str):
                 lineno = self.gds_get_node_lineno_()
                 self.gds_collector_.add_message('Value "%(value)s"%(lineno)s is not of the correct base simple type (str)' % {"value": value, "lineno": lineno, })
                 return False
             value = value
-            enumerations = ['yes', 'no']
+            enumerations = ['public', 'protected', 'private', 'package']
             if value not in enumerations:
                 lineno = self.gds_get_node_lineno_()
-                self.gds_collector_.add_message('Value "%(value)s"%(lineno)s does not match xsd enumeration restriction on DoxBool' % {"value" : encode_str_2_3(value), "lineno": lineno} )
+                self.gds_collector_.add_message('Value "%(value)s"%(lineno)s does not match xsd enumeration restriction on DoxProtectionKind' % {"value" : encode_str_2_3(value), "lineno": lineno} )
                 result = False
     def hasContent_(self):
         if (
@@ -1871,6 +1877,9 @@ def exportAttributes(self, outfile, level, already_processed, namespaceprefix_='
         if self.kind is not None and 'kind' not in already_processed:
             already_processed.add('kind')
             outfile.write(' kind=%s' % (self.gds_encode(self.gds_format_string(quote_attrib(self.kind), input_name='kind')), ))
+        if self.trivial is not None and 'trivial' not in already_processed:
+            already_processed.add('trivial')
+            outfile.write(' trivial=%s' % (self.gds_encode(self.gds_format_string(quote_attrib(self.trivial), input_name='trivial')), ))
         if self.language is not None and 'language' not in already_processed:
             already_processed.add('language')
             outfile.write(' language=%s' % (self.gds_encode(self.gds_format_string(quote_attrib(self.language), input_name='language')), ))
@@ -2008,6 +2017,11 @@ def buildAttributes(self, node, attrs, already_processed):
             already_processed.add('kind')
             self.kind = value
             self.validate_DoxCompoundKind(self.kind)    # validate type DoxCompoundKind
+        value = find_attr_value_('trivial', node)
+        if value is not None and 'trivial' not in already_processed:
+            already_processed.add('trivial')
+            self.trivial = value
+            self.validate_DoxBool(self.trivial)    # validate type DoxBool
         value = find_attr_value_('language', node)
         if value is not None and 'language' not in already_processed:
             already_processed.add('language')
@@ -3741,7 +3755,7 @@ class memberdefType(GeneratedsSuper):
     __hash__ = GeneratedsSuper.__hash__
     subclass = None
     superclass = None
-    def __init__(self, kind=None, id=None, prot=None, static=None, extern=None, strong=None, const=None, explicit=None, inline=None, refqual=None, virt=None, volatile=None, mutable=None, thread_local=None, noexcept=None, noexceptexpression=None, nodiscard=None, constexpr=None, consteval=None, constinit=None, readable=None, writable=None, initonly=None, settable=None, privatesettable=None, protectedsettable=None, gettable=None, privategettable=None, protectedgettable=None, final=None, sealed=None, new=None, add=None, remove=None, raise_=None, optional=None, required=None, accessor=None, attribute=None, property=None, readonly=None, bound=None, removable=None, constrained=None, transient=None, maybevoid=None, maybedefault=None, maybeambiguous=None, templateparamlist=None, type_=None, definition=None, argsstring=None, name=None, qualifiedname=None, read=None, write=None, bitfield=None, reimplements=None, reimplementedby=None, qualifier=None, param=None, enumvalue=None, requiresclause=None, initializer=None, exceptions=None, briefdescription=None, detaileddescription=None, inbodydescription=None, location=None, references=None, referencedby=None, gds_collector_=None, **kwargs_):
+    def __init__(self, kind=None, id=None, prot=None, static=None, extern=None, trivial=None, strong=None, const=None, explicit=None, inline=None, refqual=None, virt=None, volatile=None, mutable=None, thread_local=None, noexcept=None, noexceptexpression=None, nodiscard=None, constexpr=None, consteval=None, constinit=None, readable=None, writable=None, initonly=None, settable=None, privatesettable=None, protectedsettable=None, gettable=None, privategettable=None, protectedgettable=None, final=None, sealed=None, new=None, add=None, remove=None, raise_=None, optional=None, required=None, accessor=None, attribute=None, property=None, readonly=None, bound=None, removable=None, constrained=None, transient=None, maybevoid=None, maybedefault=None, maybeambiguous=None, templateparamlist=None, type_=None, definition=None, argsstring=None, name=None, qualifiedname=None, read=None, write=None, bitfield=None, reimplements=None, reimplementedby=None, qualifier=None, param=None, enumvalue=None, requiresclause=None, initializer=None, exceptions=None, briefdescription=None, detaileddescription=None, inbodydescription=None, location=None, references=None, referencedby=None, gds_collector_=None, **kwargs_):
         self.gds_collector_ = gds_collector_
         self.gds_elementtree_node_ = None
         self.original_tagname_ = None
@@ -3757,6 +3771,8 @@ def __init__(self, kind=None, id=None, prot=None, static=None, extern=None, stro
         self.static_nsprefix_ = None
         self.extern = _cast(None, extern)
         self.extern_nsprefix_ = None
+        self.trivial = _cast(None, trivial)
+        self.trivial_nsprefix_ = None
         self.strong = _cast(None, strong)
         self.strong_nsprefix_ = None
         self.const = _cast(None, const)
@@ -4079,6 +4095,10 @@ def get_extern(self):
         return self.extern
     def set_extern(self, extern):
         self.extern = extern
+    def get_trivial(self):
+        return self.trivial
+    def set_trivial(self, trivial):
+        self.trivial = trivial
     def get_strong(self):
         return self.strong
     def set_strong(self, strong):
@@ -4397,6 +4417,9 @@ def exportAttributes(self, outfile, level, already_processed, namespaceprefix_='
         if self.extern is not None and 'extern' not in already_processed:
             already_processed.add('extern')
             outfile.write(' extern=%s' % (self.gds_encode(self.gds_format_string(quote_attrib(self.extern), input_name='extern')), ))
+        if self.trivial is not None and 'trivial' not in already_processed:
+            already_processed.add('trivial')
+            outfile.write(' trivial=%s' % (self.gds_encode(self.gds_format_string(quote_attrib(self.trivial), input_name='trivial')), ))
         if self.strong is not None and 'strong' not in already_processed:
             already_processed.add('strong')
             outfile.write(' strong=%s' % (self.gds_encode(self.gds_format_string(quote_attrib(self.strong), input_name='strong')), ))
@@ -4644,6 +4667,11 @@ def buildAttributes(self, node, attrs, already_processed):
             already_processed.add('extern')
             self.extern = value
             self.validate_DoxBool(self.extern)    # validate type DoxBool
+        value = find_attr_value_('trivial', node)
+        if value is not None and 'trivial' not in already_processed:
+            already_processed.add('trivial')
+            self.trivial = value
+            self.validate_DoxBool(self.trivial)    # validate type DoxBool
         value = find_attr_value_('strong', node)
         if value is not None and 'strong' not in already_processed:
             already_processed.add('strong')

doc/commands.dox

@@ -235,6 +235,7 @@ documentation:
 \refitem cmdthrows \\throws
 \refitem cmdtodo \\todo
 \refitem cmdtparam \\tparam
+\refitem cmdtrivial \\trivial
 \refitem cmdtypedef \\typedef
 \refitem cmdplantumlfile \\plantumlfile
 \refitem cmdunion \\union
@@ -1510,6 +1511,15 @@ Description
 
   \sa section \ref cmdfn "\\fn", \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef".
 
+<hr>
+\section cmdtrivial \\trivial
+
+  \addindex \\trivial
+  Indicates that the entity doesn't need documentation as it is "trivial", but that it should be 
+  show in the documentation anyway.
+
+  \sa \ref cfg_extract_all "EXTRACT_ALL"
+
 <hr>
 \section cmdvhdlflow \\vhdlflow [(title for the flow chart)]
 

src/classdef.cpp

@@ -207,6 +207,7 @@ class ClassDefImpl : public DefinitionMixin<ClassDefMutable>
     QCString displayName(bool includeScope=TRUE) const override;
     CompoundType compoundType() const override;
     QCString compoundTypeString() const override;
+    bool isTrivial() const override;
     const BaseClassList &baseClasses() const override;
     void updateBaseClasses(const BaseClassList &bcd) override;
     const BaseClassList &subClasses() const override;
@@ -293,6 +294,7 @@ class ClassDefImpl : public DefinitionMixin<ClassDefMutable>
     void addUsedClass(ClassDef *cd,const QCString &accessName,Protection prot) override;
     void addUsedByClass(ClassDef *cd,const QCString &accessName,Protection prot) override;
     void setIsStatic(bool b) override;
+    void setIsTrivial(bool b) override;
     void setCompoundType(CompoundType t) override;
     void setClassName(const QCString &name) override;
     void setClassSpecifier(TypeSpecifier spec) override;
@@ -510,6 +512,9 @@ class ClassDefImpl : public DefinitionMixin<ClassDefMutable>
     /*! Is the class part of an unnamed namespace? */
     bool m_isStatic = false;
 
+    /*! Is the class trivial without class documentation? */
+    bool m_isTrivial = false;
+
     /*! TRUE if classes members are merged with those of the base classes. */
     bool m_membersMerged = false;
 
@@ -612,6 +617,8 @@ class ClassDefAliasImpl : public DefinitionAliasMixin<ClassDef>
     { return getCdAlias()->compoundType(); }
     QCString compoundTypeString() const override
     { return getCdAlias()->compoundTypeString(); }
+    bool isTrivial() const override
+    { return getCdAlias()->isTrivial(); }
     const BaseClassList &baseClasses() const override
     { return getCdAlias()->baseClasses(); }
     const BaseClassList &subClasses() const override
@@ -825,6 +832,7 @@ ClassDefImpl::ClassDefImpl(
   m_templateMaster =nullptr;
   m_isAbstract = FALSE;
   m_isStatic = FALSE;
+  m_isTrivial = FALSE;
   m_isTemplArg = FALSE;
   m_membersMerged = FALSE;
   m_categoryOf = nullptr;
@@ -901,6 +909,7 @@ std::unique_ptr<ClassDef> ClassDefImpl::deepCopy(const QCString &name) const
   result->m_categoryOf = m_categoryOf;
   result->m_isAbstract = m_isAbstract;
   result->m_isStatic = m_isStatic;
+  result->m_isTrivial = m_isTrivial;
   result->m_membersMerged = m_membersMerged;
   result->m_isLocal = m_isLocal;
   result->m_isTemplArg = m_isTemplArg;
@@ -3665,7 +3674,7 @@ bool ClassDefImpl::isVisibleInHierarchy() const
 
 bool ClassDefImpl::hasDocumentation() const
 {
-  return DefinitionMixin::hasDocumentation();
+  return m_isTrivial || DefinitionMixin::hasDocumentation();
 }
 
 //----------------------------------------------------------------------
@@ -5173,6 +5182,16 @@ void ClassDefImpl::setIsStatic(bool b)
   m_isStatic=b;
 }
 
+void ClassDefImpl::setIsTrivial(bool b)
+{
+  m_isTrivial=b;
+}
+
+bool ClassDefImpl::isTrivial() const
+{
+  return m_isTrivial;
+}
+
 void ClassDefImpl::setCompoundType(CompoundType t)
 {
   m_compType = t;

src/classdef.h

@@ -147,6 +147,9 @@ class ClassDef : public Definition
     /** Returns the type of compound as a string */
     virtual QCString compoundTypeString() const = 0;
 
+    /** Returns whether or not the class is trivial */
+    virtual bool isTrivial() const = 0;
+
     /** Returns the list of base classes from which this class directly
      *  inherits.
      */
@@ -385,6 +388,7 @@ class ClassDefMutable : public DefinitionMutable, public ClassDef
     virtual void setProtection(Protection p) = 0;
     virtual void setGroupDefForAllMembers(GroupDef *g,Grouping::GroupPri_t pri,const QCString &fileName,int startLine,bool hasDocs) = 0;
     virtual void setIsStatic(bool b) = 0;
+    virtual void setIsTrivial(bool b) = 0;
     virtual void setCompoundType(CompoundType t) = 0;
     virtual void setClassName(const QCString &name) = 0;
     virtual void setClassSpecifier(TypeSpecifier spec) = 0;

src/commentscan.l

@@ -147,6 +147,7 @@ static bool handleGroupgraph(yyscan_t yyscanner,const QCString &, const StringVe
 static bool handleHideGroupgraph(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleInternal(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleStatic(yyscan_t yyscanner,const QCString &, const StringVector &);
+static bool handleTrivial(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handlePure(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handlePrivate(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handlePrivateSection(yyscan_t yyscanner,const QCString &, const StringVector &);
@@ -364,6 +365,7 @@ static const std::map< std::string, DocCmdMap > docCmdMap =
   { "throws",                 { nullptr,                         CommandSpacing::Block,     SectionHandling::Break   }},
   { "todo",                   { &handleTodo,                     CommandSpacing::XRef,      SectionHandling::Break   }},
   { "tparam",                 { nullptr,                         CommandSpacing::Block,     SectionHandling::Break   }},
+  { "trivial",                { &handleTrivial,                  CommandSpacing::Invisible, SectionHandling::Escape  }},
   { "typedef",                { &handleFn,                       CommandSpacing::Invisible, SectionHandling::Escape  }},
   { "union",                  { &handleUnion,                    CommandSpacing::Invisible, SectionHandling::Escape  }},
   { "until",                  { nullptr,                         CommandSpacing::Block,     SectionHandling::Escape  }},
@@ -4020,6 +4022,13 @@ static bool handleStatic(yyscan_t yyscanner,const QCString &, const StringVector
   return FALSE;
 }
 
+static bool handleTrivial(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->isTrivial = true;
+  return FALSE;
+}
+
 static bool handlePure(yyscan_t yyscanner,const QCString &, const StringVector &)
 {
   struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;