[glibmm] gmmproc: Allow destructors to be documented.

[Josà Alburquerque <jaalburqu src gnome org>]

commit 6f92aacd7bca73679bd76d10db1ce65ef7197a29
Author: Josà Alburquerque <jaalburqu svn gnome org>
Date:   Thu Mar 1 17:06:50 2012 -0500

    gmmproc: Allow destructors to be documented.
    
    	* tools/m4/base.m4 (SECTION_DTOR_DOCUMENTATION): Add a new section in
    	which to store a destructor's documentation.
    	* tools/m4/class_shared.m4 (_DOCUMENT_DTOR): Add a new macro which
    	takes text and places it in a Doxygen comment block sending the
    	comment block to the new section above.  The text can be multiline.
    	The macro assumes that any lines below the first, if any, have at
    	least one space preceding them.  If the text is a single line, it can
    	be double quoted (the double quotes are removed).
    	* tools/m4/class_boxedtype.m4:
    	* tools/m4/class_gobject.m4:
    	* tools/m4/class_interface.m4:
    	* tools/m4/class_opaque_copyable.m4: Modify these so that any Doxygen
    	comment block sent to the new section above is inserted in the
    	generated declaration of the destructor.
    
    	Bug #668918.

 ChangeLog                         |   21 +++++++++++++++++++++
 tools/m4/base.m4                  |    3 +++
 tools/m4/class_boxedtype.m4       |    1 +
 tools/m4/class_gobject.m4         |    1 +
 tools/m4/class_interface.m4       |    1 +
 tools/m4/class_opaque_copyable.m4 |    1 +
 tools/m4/class_shared.m4          |   21 +++++++++++++++++++++
 7 files changed, 49 insertions(+), 0 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 4cf1742..435526f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,24 @@
+2012-03-01  Josà Alburquerque  <jaalburquerque gmail com>
+
+	gmmproc: Allow destructors to be documented.
+
+	* tools/m4/base.m4 (SECTION_DTOR_DOCUMENTATION): Add a new section in
+	which to store a destructor's documentation.
+	* tools/m4/class_shared.m4 (_DOCUMENT_DTOR): Add a new macro which
+	takes text and places it in a Doxygen comment block sending the
+	comment block to the new section above.  The text can be multiline.
+	The macro assumes that any lines below the first, if any, have at
+	least one space preceding them.  If the text is a single line, it can
+	be double quoted (the double quotes are removed).  
+	* tools/m4/class_boxedtype.m4:
+	* tools/m4/class_gobject.m4:
+	* tools/m4/class_interface.m4:
+	* tools/m4/class_opaque_copyable.m4: Modify these so that any Doxygen
+	comment block sent to the new section above is inserted in the
+	generated declaration of the destructor.
+
+	Bug #668918.
+
 2012-02-29  Josà Alburquerque  <jaalburquerque gmail com>
 
 	Generation Scripts: Don't assume the root directory is glibmm.
diff --git a/tools/m4/base.m4 b/tools/m4/base.m4
index 6843125..b6b61e2 100644
--- a/tools/m4/base.m4
+++ b/tools/m4/base.m4
@@ -213,6 +213,9 @@ dnl _NEW_SECTION(SECTION_PCC_OBJECT_INIT) dnl  gtk+ object_init function
 _NEW_SECTION(SECTION_CHECK)
 _NEW_SECTION(SECTION_USR)
 
+dnl Used for documenting destructors if desired.
+_NEW_SECTION(SECTION_DTOR_DOCUMENTATION)
+
 define(`_CHECK',`dnl
 _PUSH(SECTION_CHECK)
     $*
diff --git a/tools/m4/class_boxedtype.m4 b/tools/m4/class_boxedtype.m4
index 65f019e..f3186d4 100644
--- a/tools/m4/class_boxedtype.m4
+++ b/tools/m4/class_boxedtype.m4
@@ -196,6 +196,7 @@ ifdef(`__BOOL_CUSTOM_DEFAULT_CTOR__',`dnl
   __CPPNAME__`'(const __CPPNAME__& other);
   __CPPNAME__& operator=(const __CPPNAME__& other);
 
+_IMPORT(SECTION_DTOR_DOCUMENTATION)
   ~__CPPNAME__`'();
 
   void swap(__CPPNAME__& other);
diff --git a/tools/m4/class_gobject.m4 b/tools/m4/class_gobject.m4
index 9462de4..f56fd7a 100644
--- a/tools/m4/class_gobject.m4
+++ b/tools/m4/class_gobject.m4
@@ -244,6 +244,7 @@ protected:
 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
 public:
+_IMPORT(SECTION_DTOR_DOCUMENTATION)
   virtual ~__CPPNAME__`'();
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
diff --git a/tools/m4/class_interface.m4 b/tools/m4/class_interface.m4
index 48cfdaf..515a7a7 100644
--- a/tools/m4/class_interface.m4
+++ b/tools/m4/class_interface.m4
@@ -249,6 +249,7 @@ protected:
 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
 public:
+_IMPORT(SECTION_DTOR_DOCUMENTATION)
   virtual ~__CPPNAME__`'();
 
   static void add_interface(GType gtype_implementer);
diff --git a/tools/m4/class_opaque_copyable.m4 b/tools/m4/class_opaque_copyable.m4
index 574f093..9223e88 100644
--- a/tools/m4/class_opaque_copyable.m4
+++ b/tools/m4/class_opaque_copyable.m4
@@ -167,6 +167,7 @@ ifdef(`__BOOL_CUSTOM_DEFAULT_CTOR__',`dnl
   __CPPNAME__`'(const __CPPNAME__& src);
   __CPPNAME__& operator=(const __CPPNAME__& src);
 
+_IMPORT(SECTION_DTOR_DOCUMENTATION)
   ~__CPPNAME__`'();
 
   __CNAME__*       gobj()       { return gobject_; }
diff --git a/tools/m4/class_shared.m4 b/tools/m4/class_shared.m4
index f807de6..f91c343 100644
--- a/tools/m4/class_shared.m4
+++ b/tools/m4/class_shared.m4
@@ -57,6 +57,27 @@ define(`__BOOL_DYNAMIC_GTYPE_REGISTRATION__',`$1')
 _POP()
 ')
 
+dnl This macro inserts the supplied text as a Doxygen comment block before the
+dnl automatically generated declaration of a class' destructor.  The inner
+dnl m4_ifelse() attempts to remove double quotes before and after the text if
+dnl it is a single line.  If it is not, it returns the supplied lines, removing
+dnl trailing spaces from each of them (with an m4_patsubst()).  The following
+dnl outer m4_patsubst() prepends possible multiple lines below the first one
+dnl with ' * ' by assuming that these lines are preceded by at least one space.
+dnl Finally, the outer m4_patsubst() inserts spaces after commas which are
+dnl removed by m4 in the processing.
+dnl
+dnl
+dnl
+dnl
+define(`_DOCUMENT_DTOR',`dnl
+_PUSH(SECTION_DTOR_DOCUMENTATION)
+m4_ifelse(`$*',,,`dnl
+  m4_patsubst(`m4_patsubst(`/** m4_ifelse(m4_regexp(`$*',`".*"'),-1,`m4_patsubst(`$*',`\s*$')',`m4_regexp(`$*',`"\s*\(.*\)\(\S\)\s*"',`\1\2')')',`^\s+',`   * ')',`,',`, ')
+   */
+')dnl
+_POP()
+')