GNOME.org
 

[libsigc++2] Documentation: Fix many warnings from Doxygen.

commit 7c6ff314507bd0beb3b92ebf0a0f6258b67d7796
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Mon Jan 7 10:24:16 2013 +0100

    Documentation: Fix many warnings from Doxygen.
    
    * configure.ac: Require mm-common 0.9.6 or later.
    * docs/reference/Doxyfile.in: Don't warn for undocumented classes and structs.
    * sigc++/adaptors/macros/bind.h.m4:
    * sigc++/adaptors/macros/bind_return.h.m4:
    * sigc++/adaptors/macros/compose.h.m4:
    * sigc++/adaptors/macros/hide.h.m4:
    * sigc++/connection.h:
    * sigc++/macros/limit_reference.h.m4: Make all parameter names in @param
    commands equal to the corresponding names in the function declarations.
    * sigc++/signal_base.h: Remove an extraneous period that confuses Doxygen.
    * sigc++/type_traits.h: Add a missing @code/@endcode pair.

 ChangeLog                               |   16 ++++++++++++++++
 configure.ac                            |    2 +-
 docs/reference/Doxyfile.in              |   12 ++++++++++--
 sigc++/adaptors/macros/bind.h.m4        |    7 ++++---
 sigc++/adaptors/macros/bind_return.h.m4 |    4 ++--
 sigc++/adaptors/macros/compose.h.m4     |    3 +--
 sigc++/adaptors/macros/hide.h.m4        |   14 +++++++-------
 sigc++/connection.h                     |    2 +-
 sigc++/macros/limit_reference.h.m4      |    2 +-
 sigc++/signal_base.h                    |    2 +-
 sigc++/type_traits.h                    |    4 +++-
 11 files changed, 47 insertions(+), 21 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index f194172..4c75b9e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2013-01-07  Kjell Ahlstedt  <kjell ahlstedt bredband net>
+
+	Documentation: Fix many warnings from Doxygen.
+
+	* configure.ac: Require mm-common 0.9.6 or later.
+	* docs/reference/Doxyfile.in: Don't warn for undocumented classes and structs.
+	* sigc++/adaptors/macros/bind.h.m4:
+	* sigc++/adaptors/macros/bind_return.h.m4:
+	* sigc++/adaptors/macros/compose.h.m4:
+	* sigc++/adaptors/macros/hide.h.m4:
+	* sigc++/connection.h:
+	* sigc++/macros/limit_reference.h.m4: Make all parameter names in @param
+	commands equal to the corresponding names in the function declarations.
+	* sigc++/signal_base.h: Remove an extraneous period that confuses Doxygen.
+	* sigc++/type_traits.h: Add a missing @code/@endcode pair.
+
 2012-10-18  Kjell Ahlstedt  <kjell ahlstedt bredband net>
 
 	Test cases: Report pass/fail with exit status.
diff --git a/configure.ac b/configure.ac
index 864b340..57d9a31 100644
--- a/configure.ac
+++ b/configure.ac
@@ -30,7 +30,7 @@ m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES])
 AM_MAINTAINER_MODE
 AC_ARG_VAR([ACLOCAL_FLAGS], [aclocal flags, e.g. -I <macro dir>])
 
-MM_PREREQ([0.7.2])
+MM_PREREQ([0.9.6])
 MM_INIT_MODULE([sigc++-2.0])
 MM_CONFIG_DOCTOOL_DIR([docs])
 
diff --git a/docs/reference/Doxyfile.in b/docs/reference/Doxyfile.in
index 32da806..63d5618 100644
--- a/docs/reference/Doxyfile.in
+++ b/docs/reference/Doxyfile.in
@@ -1,4 +1,5 @@
 # Doxyfile 1.8.2
+# @configure_input@
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
@@ -358,6 +359,13 @@ LOOKUP_CACHE_SIZE      = 0
 # Build related configuration options
 #---------------------------------------------------------------------------
 
+# TODO: Most mm packages have EXTRACT_ALL = YES and WARN_IF_UNDOCUMENTED = YES,
+#       and they use DOXYGEN_SHOULD_SKIP_THIS to mark what Doxygen shall not
+#       extract. libsigc++ ought to use this method, but at present (2013-01-07)
+#       it does not use DOXYGEN_SHOULD_SKIP_THIS consistently, and
+#       EXTRACT_ALL = YES includes scores of undocumented uninteresting template
+#       specializations in the documentation.
+
 # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
 # documentation are documented, even if no documentation was available.
 # Private class members and static file members will be hidden unless
@@ -539,7 +547,7 @@ GENERATE_BUGLIST       = NO
 # disable (NO) the deprecated list. This list is created by putting
 # \deprecated commands in the documentation.
 
-GENERATE_DEPRECATEDLIST= NO
+GENERATE_DEPRECATEDLIST= YES
 
 # The ENABLED_SECTIONS tag can be used to enable conditional
 # documentation sections, marked by \if sectionname ... \endif.
@@ -623,7 +631,7 @@ WARNINGS               = YES
 # for undocumented members. If EXTRACT_ALL is set to YES then this flag will
 # automatically be disabled.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some
diff --git a/sigc++/adaptors/macros/bind.h.m4 b/sigc++/adaptors/macros/bind.h.m4
index cd360f6..58c0a4f 100644
--- a/sigc++/adaptors/macros/bind.h.m4
+++ b/sigc++/adaptors/macros/bind.h.m4
@@ -101,7 +101,7 @@ struct bind_functor<$1, T_functor, T_bound, LIST(LOOP(nil, CALL_SIZE - 1))> : pu
 
 FOR(eval($1+1),CALL_SIZE,[[BIND_OPERATOR_LOCATION(eval($1+1),%1)]])dnl
   /** Constructs a bind_functor object that binds an argument to the passed functor.
-   * @param _A_functor Functor to invoke from operator()().
+   * @param _A_func Functor to invoke from operator()().
    * @param _A_bound Argument to bind to the functor.
    */
   bind_functor(_R_(T_functor) _A_func, _R_(T_bound) _A_bound)
@@ -150,8 +150,9 @@ FOR(eval($1+1),eval(CALL_SIZE-1),[[DEDUCE_RESULT_TYPE_COUNT($1,%1)]])dnl
 
 FOR(2,eval(CALL_SIZE-$1+1),[[BIND_OPERATOR_COUNT($1,%1)]])dnl
   /** Constructs a bind_functor object that binds an argument to the passed functor.
-   * @param _A_functor Functor to invoke from operator()().
-   * @param _A_bound Argument to bind to the functor.
+   * @param _A_func Functor to invoke from operator()().dnl
+FOR(1,$1,[
+   * @param _A_bound%1 Argument to bind to the functor.])
    */
   bind_functor(_R_(T_functor) _A_func, LOOP(_R_(T_type%1) _A_bound%1, $1))
     : adapts<T_functor>(_A_func), LOOP(bound%1_(_A_bound%1), $1)
diff --git a/sigc++/adaptors/macros/bind_return.h.m4 b/sigc++/adaptors/macros/bind_return.h.m4
index 6a6d8ac..0ecbdc6 100644
--- a/sigc++/adaptors/macros/bind_return.h.m4
+++ b/sigc++/adaptors/macros/bind_return.h.m4
@@ -20,8 +20,8 @@ include(template.macros.m4)
 
 define([BIND_RETURN_OPERATOR],[dnl
   /** Invokes the wrapped functor passing on the arguments.dnl
-FOR(1, $1),[
-   * @param _A_arg%1 Argument to be passed on to the functor.])
+FOR(1, $1,[
+   * @param _A_a%1 Argument to be passed on to the functor.])
    * @return The fixed return value.
    */
   template <LOOP(class T_arg%1, $1)>
diff --git a/sigc++/adaptors/macros/compose.h.m4 b/sigc++/adaptors/macros/compose.h.m4
index 5298801..3cf0928 100644
--- a/sigc++/adaptors/macros/compose.h.m4
+++ b/sigc++/adaptors/macros/compose.h.m4
@@ -106,8 +106,7 @@ FOR(1,CALL_SIZE, [[COMPOSE1_OPERATOR(%1)]])dnl
 
   /** Constructs a compose1_functor object that combines the passed functors.
    * @param _A_setter Functor that receives the return values of the invokation of @e _A_getter1 and @e _A_getter2.
-   * @param _A_getter1 Functor to invoke from operator()().
-   * @param _A_getter2 Functor to invoke from operator()().
+   * @param _A_getter Functor to invoke from operator()().
    */
   compose1_functor(const T_setter& _A_setter, const T_getter& _A_getter)
     : adapts<T_setter>(_A_setter), get_(_A_getter)
diff --git a/sigc++/adaptors/macros/hide.h.m4 b/sigc++/adaptors/macros/hide.h.m4
index 030c387..0ef3384 100644
--- a/sigc++/adaptors/macros/hide.h.m4
+++ b/sigc++/adaptors/macros/hide.h.m4
@@ -31,7 +31,7 @@ define([HIDE_OPERATOR],[dnl
 ifelse($2,0,,[dnl
 ifelse($2,1,[dnl
   /** Invokes the wrapped functor ignoring the only argument.
-   * @param _A_arg%1 Argument to be ignored.
+   * @param _A_a1 Argument to be ignored.
    * @return The return value of the functor invocation.
    */
   template <class T_arg1>
@@ -49,8 +49,8 @@ ifelse($2,1,[dnl
 ],$1,0,[dnl
   /** Invokes the wrapped functor, ignoring the last argument.dnl
 FOR(1, eval($2-1),[
-   * @param _A_arg%1 Argument to be passed on to the functor.])
-   * @param _A_arg$2 Argument to be ignored.
+   * @param _A_a%1 Argument to be passed on to the functor.])
+   * @param _A_a$2 Argument to be ignored.
    * @return The return value of the functor invocation.
    */
   template <LOOP([class T_arg%1], $2)>
@@ -70,10 +70,10 @@ FOR(1, eval($2-1),[
 ],[dnl
   /** Invokes the wrapped functor, ignoring the $1[]th argument.dnl
 FOR(1, eval($1-1),[
-   * @param _A_arg%1 Argument to be passed on to the functor.])
-   * @param _A_arg$1 Argument to be ignored.dnl
+   * @param _A_a%1 Argument to be passed on to the functor.])
+   * @param _A_a$1 Argument to be ignored.dnl
 FOR(eval($1+1), $2,[
-   * @param _A_arg%1 Argument to be passed on to the functor.])
+   * @param _A_a%1 Argument to be passed on to the functor.])
    * @return The return value of the functor invocation.
    */
   template <LOOP([class T_arg%1], $2)>
@@ -109,7 +109,7 @@ DEDUCE_RESULT_TYPE(eval($1+1),CALL_SIZE)dnl
 FOR(eval($1+1),CALL_SIZE,[[HIDE_OPERATOR(eval($1+1),%1)]])dnl
 
   /** Constructs a hide_functor object that adds a dummy parameter to the passed functor.
-   * @param _A_functor Functor to invoke from operator()().
+   * @param _A_func Functor to invoke from operator()().
    */
   explicit hide_functor(const T_functor& _A_func)
     : adapts<T_functor>(_A_func)
diff --git a/sigc++/connection.h b/sigc++/connection.h
index c8855e6..348afe9 100644
--- a/sigc++/connection.h
+++ b/sigc++/connection.h
@@ -110,7 +110,7 @@ struct SIGC_API connection
   operator bool();
 
   /** Callback that is executed when the referred slot is destroyed.
-   * @param d The connection object notified (@p this).
+   * @param data The connection object notified (@p this).
    */
   static void* notify(void* data);
 
diff --git a/sigc++/macros/limit_reference.h.m4 b/sigc++/macros/limit_reference.h.m4
index c40acc2..25976fa 100644
--- a/sigc++/macros/limit_reference.h.m4
+++ b/sigc++/macros/limit_reference.h.m4
@@ -118,7 +118,7 @@ private:
  * - @e T_action The type of functor to invoke.
  * - @e T_type The type of the reference.
  * @param _A_action The functor to invoke.
- * @param _A_argument The visited instance.
+ * @param _A_target The visited instance.
  */
 template <class T_action, class T_type, bool I_derives_trackable>
 void
diff --git a/sigc++/signal_base.h b/sigc++/signal_base.h
index cd5a62f..3b972ab 100644
--- a/sigc++/signal_base.h
+++ b/sigc++/signal_base.h
@@ -302,7 +302,7 @@ struct SIGC_API signal_base : public trackable
    */
   void block(bool should_block = true);
 
-  /** Unsets the blocking state of all slots in the list..
+  /** Unsets the blocking state of all slots in the list.
    *
    * @newin{2,4}
    */
diff --git a/sigc++/type_traits.h b/sigc++/type_traits.h
index b2c1a7e..ba89884 100644
--- a/sigc++/type_traits.h
+++ b/sigc++/type_traits.h
@@ -78,6 +78,7 @@ struct type_trait<void>
  * Use this to provide a template specialization for a set of types.
  * For instance,
  *
+ * @code
  * template < class T_thing, bool Tval_derives_from_something = sigc::is_base_and_derived<Something, T_thing>::value >
  * class TheTemplate
  * {
@@ -89,8 +90,9 @@ struct type_trait<void>
  * class TheTemplate<T_thing, true>
  * {
  *   T_thing thing;
-     thing.method_that_is_in_something();
+ *   thing.method_that_is_in_something();
  * }
+ * @endcode
  */
 template <class T_base, class T_derived>
 struct is_base_and_derived
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]