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.

7 files changed, 49 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 4cf17421..435526f0 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 68431253..b6b61e2c 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 65f019e9..f3186d41 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 9462de46..f56fd7ae 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 48cfdaf1..515a7a7b 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 574f093a..9223e88c 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 f807de6d..f91c3439 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()
+')