Use DOXYGEN_SHOULD_SKIP_THIS consistently.

* docs/reference/Doxyfile.in: EXTRACT_ALL=YES, like in most mm packages.
* sigc++/sigc++.h: Mention that the reference manual contains only some of
the template specializations.
* sigc++/adaptors/bound_argument.h:
* sigc++/adaptors/lambda/macros/base.h.m4:
* sigc++/adaptors/lambda/macros/group.h.m4:
* sigc++/adaptors/macros/adaptor_trait.h.m4:
* sigc++/adaptors/macros/bind.h.m4:
* sigc++/adaptors/macros/bind_return.h.m4:
* sigc++/adaptors/macros/compose.h.m4:
* sigc++/adaptors/macros/deduce_result_type.h.m4:
* sigc++/adaptors/macros/exception_catch.h.m4:
* sigc++/adaptors/macros/hide.h.m4:
* sigc++/adaptors/macros/retype.h.m4:
* sigc++/adaptors/macros/retype_return.h.m4:
* sigc++/adaptors/macros/track_obj.h.m4:
* sigc++/functors/macros/functor_trait.h.m4:
* sigc++/functors/macros/mem_fun.h.m4:
* sigc++/macros/limit_reference.h.m4:
* sigc++/type_traits.h:
* sigc++/visit_each.h: Use DOXYGEN_SHOULD_SKIP_THIS to mark what Doxygen
shall not extract.

21 files changed, 162 insertions, 54 deletions

diff --git a/ChangeLog b/ChangeLog
index 581d665..e2bb620 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,30 @@
+2013-04-11  Kjell Ahlstedt  <kjell.ahlstedt@bredband.net>
+
+	Use DOXYGEN_SHOULD_SKIP_THIS consistently.
+
+	* docs/reference/Doxyfile.in: EXTRACT_ALL=YES, like in most mm packages.
+	* sigc++/sigc++.h: Mention that the reference manual contains only some of
+	the template specializations.
+	* sigc++/adaptors/bound_argument.h:
+	* sigc++/adaptors/lambda/macros/base.h.m4:
+	* sigc++/adaptors/lambda/macros/group.h.m4:
+	* sigc++/adaptors/macros/adaptor_trait.h.m4:
+	* sigc++/adaptors/macros/bind.h.m4:
+	* sigc++/adaptors/macros/bind_return.h.m4:
+	* sigc++/adaptors/macros/compose.h.m4:
+	* sigc++/adaptors/macros/deduce_result_type.h.m4:
+	* sigc++/adaptors/macros/exception_catch.h.m4:
+	* sigc++/adaptors/macros/hide.h.m4:
+	* sigc++/adaptors/macros/retype.h.m4:
+	* sigc++/adaptors/macros/retype_return.h.m4:
+	* sigc++/adaptors/macros/track_obj.h.m4:
+	* sigc++/functors/macros/functor_trait.h.m4:
+	* sigc++/functors/macros/mem_fun.h.m4:
+	* sigc++/macros/limit_reference.h.m4:
+	* sigc++/type_traits.h:
+	* sigc++/visit_each.h: Use DOXYGEN_SHOULD_SKIP_THIS to mark what Doxygen
+	shall not extract.
+
 2013-03-20  Kjell Ahlstedt  <kjell.ahlstedt@bredband.net>
 
 	Suppress erroneous links in documentation.
diff --git a/docs/reference/Doxyfile.in b/docs/reference/Doxyfile.in
index 63d5618..b9d0daa 100644
--- a/docs/reference/Doxyfile.in
+++ b/docs/reference/Doxyfile.in
@@ -359,19 +359,12 @@ 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
 # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class
 # will be included in the documentation.
@@ -422,7 +415,7 @@ HIDE_UNDOC_MEMBERS     = NO
 # If set to NO (the default) these classes will be included in the various
 # overviews. This option has no effect if EXTRACT_ALL is enabled.
 
-HIDE_UNDOC_CLASSES     = YES
+HIDE_UNDOC_CLASSES     = NO
 
 # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
 # friend (class|struct|union) declarations.
@@ -488,7 +481,7 @@ SORT_MEMBER_DOCS       = YES
 # by member name. If set to NO (the default) the members will appear in
 # declaration order.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen
 # will sort the (brief and detailed) documentation of class members so that
@@ -631,7 +624,7 @@ WARNINGS               = YES
 # for undocumented members. If EXTRACT_ALL is set to YES then this flag will
 # automatically be disabled.
 
-WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_UNDOCUMENTED   = YES
 
 # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some
@@ -727,11 +720,8 @@ EXCLUDE_PATTERNS       =
 # AClass::ANamespace, ANamespace::*Test
 
 EXCLUDE_SYMBOLS        = _* \
-                         adaptor_trait \
                          basic_filebuf \
-                         basic_streambuf \
                          binary_function \
-                         char_traits \
                          internal \
                          pair \
                          unary_function
@@ -869,7 +859,7 @@ ALPHABETICAL_INDEX     = YES
 # the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
 # in which this list will be split (can be a number in the range [1..20])
 
-COLS_IN_ALPHA_INDEX    = 5
+COLS_IN_ALPHA_INDEX    = 1
 
 # In case all classes in a project start with a common prefix, all
 # classes will be put under the same header in the alphabetical index.
diff --git a/sigc++/adaptors/bound_argument.h b/sigc++/adaptors/bound_argument.h
index f6c65af..bad1fdb 100644
--- a/sigc++/adaptors/bound_argument.h
+++ b/sigc++/adaptors/bound_argument.h
@@ -142,6 +142,7 @@ private:
   const_limit_reference<T_wrapped> visited_;
 };
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 /** Implementation of visit_each() specialized for the bound_argument class.
  * Call visit_each() on the entity returned by the bound_argument's visit()
  * method.
@@ -157,7 +158,7 @@ visit_each(const T_action& _A_action,
 {
   visit_each(_A_action, _A_argument.visit());
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 } /* namespace sigc */
 
diff --git a/sigc++/adaptors/lambda/macros/base.h.m4 b/sigc++/adaptors/lambda/macros/base.h.m4
index 9973ee1..274aa65 100644
--- a/sigc++/adaptors/lambda/macros/base.h.m4
+++ b/sigc++/adaptors/lambda/macros/base.h.m4
@@ -102,10 +102,10 @@ namespace sigc {
  */
 struct lambda_base : public adaptor_base {};
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 // Forward declaration of lambda.
 template <class T_type> struct lambda;
 
-
 namespace internal {
 
 /** Abstracts lambda functionality.
@@ -146,12 +146,10 @@ FOR(1,CALL_SIZE,[[LAMBDA_DO(%1)]])dnl
   T_type value_;
 };
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <class T_type>
 typename lambda_core<T_type, true>::result_type
 lambda_core<T_type, true>::operator()() const
   { return value_(); }
-#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Abstracts lambda functionality (template specialization for other value types).
  *
@@ -177,16 +175,13 @@ FOR(1,CALL_SIZE,[[LAMBDA_DO_VALUE(%1)]])dnl
   T_type value_;
 };
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <class T_type>
 typename lambda_core<T_type, false>::result_type lambda_core<T_type, false>::operator()() const
   { return value_; }
-#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 } /* namespace internal */
 
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 template <class T_action, class T_functor, bool I_islambda>
 void visit_each(const T_action& _A_action,
@@ -194,7 +189,6 @@ void visit_each(const T_action& _A_action,
 {
   visit_each(_A_action, _A_target.value_);
 }
-#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 // forward declarations for lambda operators other<subscript> and other<assign>
 template <class T_type>
@@ -207,7 +201,7 @@ struct lambda_operator;
 
 template <class T_type>
 struct unwrap_lambda_type;
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Gets the object stored inside a lambda object.
  * Returns the object passed as argument, if it is not of type lambda.
diff --git a/sigc++/adaptors/lambda/macros/group.h.m4 b/sigc++/adaptors/lambda/macros/group.h.m4
index 65e54be..fb7ccdd 100644
--- a/sigc++/adaptors/lambda/macros/group.h.m4
+++ b/sigc++/adaptors/lambda/macros/group.h.m4
@@ -62,7 +62,7 @@ dnl Please someone get a gun!
 ])
 dnl
 dnl This really doesn't have much to do with lambda other than
-dnl holding lambdas with in itself.
+dnl holding lambdas within itself.
 define([LAMBDA_GROUP],[dnl
 /** lambda_group$1 wraps a functor and rebuilds its arguments from $1 lambda expressions.
  * Use the convenience function group() to create an instance of lambda_group$1.
@@ -79,12 +79,14 @@ FOR(1, $1,[
   typedef typename lambda<T_type%1>::lambda_type   value%1_type;])
   typedef typename adaptor_trait<T_functor>::adaptor_type functor_type;
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1=void,$2)>
   struct deduce_result_type
     { typedef typename functor_type::template deduce_result_type<LOOP([
           typename value%1_type::template deduce_result_type<LOOP([
             _P_(T_arg%1)],$2)>::type],$1)
         >::type type; };
+#endif
 
   result_type
   operator ()() const;
diff --git a/sigc++/adaptors/macros/adaptor_trait.h.m4 b/sigc++/adaptors/macros/adaptor_trait.h.m4
index 7943a19..b0782af 100644
--- a/sigc++/adaptors/macros/adaptor_trait.h.m4
+++ b/sigc++/adaptors/macros/adaptor_trait.h.m4
@@ -96,7 +96,9 @@ namespace sigc {
 #endif
 
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <class T_functor> struct adapts;
+#endif
 
 /** @defgroup adaptors Adaptors
  * Adaptors are functors that alter the signature of a functor's
@@ -129,9 +131,11 @@ template <class T_functor> struct adapts;
 template <class T_functor>
 struct adaptor_functor : public adaptor_base
 {
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
     { typedef typename sigc::deduce_result_type<LIST(T_functor, LOOP(T_arg%1,CALL_SIZE))>::type type; };
+#endif
   typedef typename functor_trait<T_functor>::result_type result_type;
 
   /** Invokes the wrapped functor passing on the arguments.
@@ -175,7 +179,7 @@ typename adaptor_functor<T_functor>::result_type
 adaptor_functor<T_functor>::operator()() const
   { return functor_(); }
 
-
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::adaptor_functor performs a functor
@@ -191,7 +195,7 @@ void visit_each(const T_action& _A_action,
   //situations.
   sigc::visit_each(_A_action, _A_target.functor_);
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Trait that specifies what is the adaptor version of a functor type.
  * Template specializations for sigc::adaptor_base derived functors,
@@ -202,7 +206,11 @@ void visit_each(const T_action& _A_action,
  *
  * @ingroup adaptors
  */
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <class T_functor, bool I_isadaptor = is_base_and_derived<adaptor_base, T_functor>::value> struct adaptor_trait;
+#else
+template <class T_functor, bool I_isadaptor = is_base_and_derived<adaptor_base, T_functor>::value> struct adaptor_trait {};
+#endif
 
 /** Trait that specifies what is the adaptor version of a functor type.
  * This template specialization is used for types that inherit from adaptor_base.
diff --git a/sigc++/adaptors/macros/bind.h.m4 b/sigc++/adaptors/macros/bind.h.m4
index 58c0a4f..1d230cd 100644
--- a/sigc++/adaptors/macros/bind.h.m4
+++ b/sigc++/adaptors/macros/bind.h.m4
@@ -18,6 +18,9 @@ divert(-1)
 
 include(template.macros.m4)
 
+define([ORDINAL],[dnl
+$1[]ifelse($1,1,[st],$1,2,[nd],$1,3,[rd],[th])[]dnl
+])
 define([DEDUCE_RESULT_TYPE_COUNT],[dnl
   template <LOOP(class T_arg%1, eval(CALL_SIZE))>
   struct deduce_result_type_internal<LIST($2, LOOP(T_arg%1,eval(CALL_SIZE)))>
@@ -26,7 +29,7 @@ define([DEDUCE_RESULT_TYPE_COUNT],[dnl
 define([BIND_OPERATOR_LOCATION],[dnl
 ifelse($2,1,,[dnl
   /** Invokes the wrapped functor passing on the arguments.
-   * bound_ is passed as the $1[]th argument.dnl
+   * bound_ is passed as the ORDINAL($1) argument.dnl
 FOR(1, eval($2-1),[
    * @param _A_arg%1 Argument to be passed on to the functor.])
    * @return The return value of the functor invocation.
@@ -74,8 +77,10 @@ FOR(1, eval($2-1),[
     
 ])
 define([BIND_FUNCTOR_LOCATION],[dnl
+ifelse($1,1,[#ifndef DOXYGEN_SHOULD_SKIP_THIS
+],)dnl Include only the first template specialization in the documentation. ($1 = 0..CALL_SIZE-1)
 /** Adaptor that binds an argument to the wrapped functor.
- * This template specialization fixes the eval($1+1)[]th argument of the wrapped functor.
+ * This template specialization fixes the ORDINAL(eval($1+1)) argument of the wrapped functor.
  *
  * @ingroup bind
  */
@@ -84,9 +89,13 @@ struct bind_functor<$1, T_functor, T_bound, LIST(LOOP(nil, CALL_SIZE - 1))> : pu
 {
   typedef typename adapts<T_functor>::adaptor_type adaptor_type;
 
+ifelse($1,0,[#ifndef DOXYGEN_SHOULD_SKIP_THIS
+],)dnl
   template <LOOP(class T_arg%1=void, eval(CALL_SIZE))>
   struct deduce_result_type
     { typedef typename adaptor_type::template deduce_result_type<LIST(LOOP(_P_(T_arg%1),eval($1)), _P_(typename unwrap_reference<T_bound>::type), FOR(eval($1+1),eval(CALL_SIZE-1),[_P_(T_arg%1),]))>::type type; };
+ifelse($1,0,[#endif
+],)dnl
   typedef typename adaptor_type::result_type  result_type;
 
   /** Invokes the wrapped functor passing on the bound argument only.
@@ -111,8 +120,11 @@ FOR(eval($1+1),CALL_SIZE,[[BIND_OPERATOR_LOCATION(eval($1+1),%1)]])dnl
   /// The argument bound to the functor.
   bound_argument<T_bound> bound_;
 };
+ifelse($1,eval(CALL_SIZE-1),[#endif // DOXYGEN_SHOULD_SKIP_THIS
+],)dnl Include only the first template specialization in the documentation. ($1 = 0..CALL_SIZE-1)
+
+])dnl end BIND_FUNCTOR_LOCATION
 
-])
 define([BIND_FUNCTOR_COUNT],[dnl
 /** Adaptor that binds $1 argument(s) to the wrapped functor.
  * This template specialization fixes the last $1 argument(s) of the wrapped functor.
@@ -124,18 +136,20 @@ struct bind_functor<LIST(-1, T_functor, LIST(LOOP(T_type%1, $1), LOOP(nil, CALL_
 {
   typedef typename adapts<T_functor>::adaptor_type adaptor_type;
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
+ifelse($1,1,[#ifndef DOXYGEN_SHOULD_SKIP_THIS
+],)dnl
   template <LIST(int count, LOOP(class T_arg%1, eval(CALL_SIZE)))>
   struct deduce_result_type_internal
     { typedef typename adaptor_type::template deduce_result_type<LIST(LOOP(_P_(T_arg%1), eval(CALL_SIZE-$1)), LOOP(_P_(typename unwrap_reference<T_type%1>::type), $1))>::type type; };
 FOR(eval($1+1),eval(CALL_SIZE-1),[[DEDUCE_RESULT_TYPE_COUNT($1,%1)]])dnl
-#endif /*DOXYGEN_SHOULD_SKIP_THIS*/
 
   template <LOOP(class T_arg%1=void, eval(CALL_SIZE))>
   struct deduce_result_type {
     typedef typename deduce_result_type_internal<internal::count_void<LOOP(T_arg%1, eval(CALL_SIZE))>::value,
                                                  LOOP(T_arg%1, eval(CALL_SIZE))>::type type;
   };
+ifelse($1,1,[#endif // DOXYGEN_SHOULD_SKIP_THIS
+],)dnl
   typedef typename adaptor_type::result_type  result_type;
 
   /** Invokes the wrapped functor passing on the bound argument only.
@@ -163,7 +177,9 @@ FOR(1,$1,[
   bound_argument<T_type%1> bound%1_;])
 };
 
-
+ifelse($1,1,[#ifndef DOXYGEN_SHOULD_SKIP_THIS
+],)dnl Include only the first template specialization of bind_functor and no
+dnl template specialization of visit_each in the documentation. ($1 = 1..CALL_SIZE)
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::bind_functor performs a functor on the
@@ -179,8 +195,11 @@ void visit_each(const T_action& _A_action,
 FOR(1,$1,[
   visit_each(_A_action, _A_target.bound%1_);])
 }
+ifelse($1,CALL_SIZE,[#endif // DOXYGEN_SHOULD_SKIP_THIS
+],)dnl
+
+])dnl end BIND_FUNCTOR_COUNT
 
-])
 define([BIND_COUNT],[dnl
 /** Creates an adaptor of type sigc::bind_functor which fixes the last $1 argument(s) of the passed functor.
  * This function overload fixes the last $1 argument(s) of @e _A_func.
@@ -326,18 +345,23 @@ struct count_void<void,void,void,void,void,void,void>
  * Use the convenience function sigc::bind() to create an instance of sigc::bind_functor.
  *
  * The following template arguments are used:
- * - @e I_location Zero-based position of the argument to fix (@p -1 for the last argument).
+ * - @e I_location Zero-based position of the argument to fix (@p -1 for the last argument).dnl
 FOR(1, CALL_SIZE,[
- * - @e T_type%1 Type of the %1st bound argument.])
+ * - @e T_type%1 Type of the [ORDINAL(%1)] bound argument.])
  * - @e T_functor Type of the functor to wrap.
  *
  * @ingroup bind
  */
 template <LIST(int I_location, class T_functor, LOOP(class T_type%1=nil, CALL_SIZE))>
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 struct bind_functor;
+#else
+struct bind_functor {};
+#endif
 
 FOR(0,eval(CALL_SIZE-1),[[BIND_FUNCTOR_LOCATION(%1)]])dnl
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::bind_functor performs a functor on the
@@ -352,6 +376,7 @@ void visit_each(const T_action& _A_action,
   visit_each(_A_action, _A_target.functor_);
   visit_each(_A_action, _A_target.bound_);
 }
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 FOR(1,CALL_SIZE,[[BIND_FUNCTOR_COUNT(%1)]])dnl
 
diff --git a/sigc++/adaptors/macros/bind_return.h.m4 b/sigc++/adaptors/macros/bind_return.h.m4
index 0ecbdc6..2c22488 100644
--- a/sigc++/adaptors/macros/bind_return.h.m4
+++ b/sigc++/adaptors/macros/bind_return.h.m4
@@ -59,9 +59,11 @@ namespace sigc {
 template <class T_return, class T_functor>
 struct bind_return_functor : public adapts<T_functor>
 {
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
     { typedef typename unwrap_reference<T_return>::type type; };
+#endif
   typedef typename unwrap_reference<T_return>::type result_type;
 
   /** Invokes the wrapped functor dropping its return value.
@@ -87,7 +89,7 @@ template <class T_return, class T_functor>
 typename unwrap_reference<T_return>::type bind_return_functor<T_return, T_functor>::operator()()
   { this->functor_(); return ret_value_.invoke(); }
 
-
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::bind_return_functor performs a functor on the
@@ -102,7 +104,7 @@ void visit_each(const T_action& _A_action,
   visit_each(_A_action, _A_target.ret_value_);
   visit_each(_A_action, _A_target.functor_);
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Creates an adaptor of type sigc::bind_return_functor which fixes the return value of the passed functor to the passed argument.
  *
diff --git a/sigc++/adaptors/macros/compose.h.m4 b/sigc++/adaptors/macros/compose.h.m4
index 3cf0928..1e445db 100644
--- a/sigc++/adaptors/macros/compose.h.m4
+++ b/sigc++/adaptors/macros/compose.h.m4
@@ -92,11 +92,13 @@ struct compose1_functor : public adapts<T_setter>
   typedef T_setter setter_type;
   typedef T_getter getter_type;
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1 = void, CALL_SIZE)>
   struct deduce_result_type
     { typedef typename adaptor_type::template deduce_result_type<
         typename sigc::deduce_result_type<LIST(T_getter, LOOP(T_arg%1,CALL_SIZE))>::type
           >::type type; };
+#endif
   typedef typename adaptor_type::result_type  result_type;
 
   result_type
@@ -138,12 +140,14 @@ struct compose2_functor : public adapts<T_setter>
   typedef T_getter1 getter1_type;
   typedef T_getter2 getter2_type;
   
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
     { typedef typename adaptor_type::template deduce_result_type<
         typename sigc::deduce_result_type<LIST(T_getter1, LOOP(T_arg%1,CALL_SIZE))>::type,
         typename sigc::deduce_result_type<LIST(T_getter2, LOOP(T_arg%1,CALL_SIZE))>::type
           >::type result_type; };
+#endif
   typedef typename adaptor_type::result_type  result_type;
 
   result_type
@@ -171,6 +175,7 @@ typename compose2_functor<T_setter, T_getter1, T_getter2>::result_type
 compose2_functor<T_setter, T_getter1, T_getter2>::operator()()
   { return this->functor_(get1_(), get2_()); }
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::compose1_functor performs a functor on the
@@ -215,7 +220,7 @@ void visit_each(const T_action& _A_action,
   typedef typename type_functor::getter2_type type_functor_getter2;
   visit_each<T_action, type_functor_getter2>(_A_action, _A_target.get2_);
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Creates an adaptor of type sigc::compose1_functor which combines two functors.
  *
diff --git a/sigc++/adaptors/macros/deduce_result_type.h.m4 b/sigc++/adaptors/macros/deduce_result_type.h.m4
index 531906b..743103e 100644
--- a/sigc++/adaptors/macros/deduce_result_type.h.m4
+++ b/sigc++/adaptors/macros/deduce_result_type.h.m4
@@ -91,7 +91,9 @@ template <class T_functor,
 struct deduce_result_type
   { typedef typename functor_trait<T_functor>::result_type type; };
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 FOR(0,CALL_SIZE,[[DEDUCE_RESULT_TYPE_ADAPTOR(%1,CALL_SIZE)]])dnl
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 dnl #ifdef SIGC_CXX_TYPEOF
 dnl FOR(0,CALL_SIZE,[[DEDUCE_RESULT_TYPE_TYPEOF(%1,CALL_SIZE)]])
diff --git a/sigc++/adaptors/macros/exception_catch.h.m4 b/sigc++/adaptors/macros/exception_catch.h.m4
index 47bff0a..ddde45c 100644
--- a/sigc++/adaptors/macros/exception_catch.h.m4
+++ b/sigc++/adaptors/macros/exception_catch.h.m4
@@ -95,9 +95,11 @@ struct exception_catch_functor : public adapts<T_functor>
 {
   typedef typename adapts<T_functor>::adaptor_type adaptor_type;
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
     { typedef typename adaptor_type::template deduce_result_type<LOOP(_P_(T_arg%1),CALL_SIZE)>::type type; };
+#endif
   typedef T_return result_type;
 
   result_type
@@ -152,7 +154,7 @@ void exception_catch_functor<T_functor, T_catcher, void>::operator()()
       { this->catcher_(); }
   }
 
-  
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 template <class T_action, class T_functor, class T_catcher, class T_return>
 void visit_each(const T_action& _A_action,
@@ -161,7 +163,7 @@ void visit_each(const T_action& _A_action,
   visit_each(_A_action, _A_target.functor_);
   visit_each(_A_action, _A_target.catcher_);
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 template <class T_functor, class T_catcher>
 inline exception_catch_functor<T_functor, T_catcher>
diff --git a/sigc++/adaptors/macros/hide.h.m4 b/sigc++/adaptors/macros/hide.h.m4
index 0ef3384..11d9060 100644
--- a/sigc++/adaptors/macros/hide.h.m4
+++ b/sigc++/adaptors/macros/hide.h.m4
@@ -18,7 +18,12 @@ divert(-1)
 
 include(template.macros.m4)
 
+define([ORDINAL],[dnl
+ifelse($1,0,,$1)ifelse($1,0,[last],$1,1,[st],$1,2,[nd],$1,3,[rd],[th])[]dnl
+])
 define([DEDUCE_RESULT_TYPE],[dnl
+ifelse(eval($1 < 2),1,[#ifndef DOXYGEN_SHOULD_SKIP_THIS
+],)dnl Only for the first two template specializations. ($1 = 0..CALL_SIZE)
   template <LOOP(class T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
 ifelse($1,0,[dnl
@@ -26,6 +31,8 @@ ifelse($1,0,[dnl
 ],[dnl
     { typedef typename adaptor_type::template deduce_result_type<LIST(LOOP(_P_(T_arg%1),eval($1-1)), FOR(eval($1+1),$2,[_P_(T_arg%1),]))>::type type; };
 ])dnl
+ifelse(eval($1 < 2),1,[#endif // DOXYGEN_SHOULD_SKIP_THIS
+],)dnl
 ])
 define([HIDE_OPERATOR],[dnl
 ifelse($2,0,,[dnl
@@ -68,7 +75,7 @@ FOR(1, eval($2-1),[
   #endif
 
 ],[dnl
-  /** Invokes the wrapped functor, ignoring the $1[]th argument.dnl
+  /** Invokes the wrapped functor, ignoring the ORDINAL($1) argument.dnl
 FOR(1, eval($1-1),[
    * @param _A_a%1 Argument to be passed on to the functor.])
    * @param _A_a$1 Argument to be ignored.dnl
@@ -91,10 +98,13 @@ FOR(eval($1+1), $2,[
   #endif
     
 ])])dnl
-])
+])dnl end HIDE_OPERATOR
+
 define([HIDE_FUNCTOR],[dnl
+ifelse($1,1,[#ifndef DOXYGEN_SHOULD_SKIP_THIS
+],)dnl Include only the first two template specializations in the documentation. ($1 = -1..CALL_SIZE-1)
 /** Adaptor that adds a dummy parameter to the wrapped functor.
- * This template specialization ignores the value of the ifelse($1,-1,[last],[$1[]th]) parameter in operator()().
+ * This template specialization ignores the value of the ORDINAL(eval($1+1)) parameter in operator()().
  *
  * @ingroup hide
  */
@@ -115,8 +125,10 @@ FOR(eval($1+1),CALL_SIZE,[[HIDE_OPERATOR(eval($1+1),%1)]])dnl
     : adapts<T_functor>(_A_func)
     {}
 };
+ifelse($1,eval(CALL_SIZE-1),[#endif // DOXYGEN_SHOULD_SKIP_THIS
+],)dnl Include only the first two template specializations in the documentation. ($1 = -1..CALL_SIZE-1)
 
-])
+])dnl end HIDE_FUNCTOR
 
 divert(0)dnl
 __FIREWALL__
@@ -187,10 +199,15 @@ namespace sigc {
  * @ingroup hide
  */
 template <int I_location, class T_functor>
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 struct hide_functor;
+#else
+struct hide_functor {};
+#endif
 
 FOR(-1,eval(CALL_SIZE-1),[[HIDE_FUNCTOR(%1)]])dnl
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::hide_functor performs a functor on the
@@ -204,7 +221,7 @@ void visit_each(const T_action& _A_action,
 {
   visit_each(_A_action, _A_target.functor_);
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Creates an adaptor of type sigc::hide_functor which adds a dummy parameter to the passed functor.
  * The optional template argument @e I_location specifies the zero-based
diff --git a/sigc++/adaptors/macros/retype.h.m4 b/sigc++/adaptors/macros/retype.h.m4
index c7297f2..69ea38f 100644
--- a/sigc++/adaptors/macros/retype.h.m4
+++ b/sigc++/adaptors/macros/retype.h.m4
@@ -139,9 +139,11 @@ struct retype_functor
 {
   typedef typename adapts<T_functor>::adaptor_type adaptor_type;
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
     { typedef typename adaptor_type::template deduce_result_type<LOOP(_P_(T_arg%1),CALL_SIZE)>::type type; };
+#endif
   typedef typename adapts<T_functor>::result_type result_type;
 
 FOR(0,CALL_SIZE,[[RETYPE_OPERATOR(%1)]])dnl
@@ -159,7 +161,7 @@ typename retype_functor<LIST(T_functor, LOOP(T_type%1, CALL_SIZE))>::result_type
 retype_functor<LIST(T_functor, LOOP(T_type%1, CALL_SIZE))>::operator()()
   { return this->functor_(); }
 
-  
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::retype_functor performs a functor on the
@@ -173,7 +175,7 @@ void visit_each(const T_action& _A_action,
 {
   visit_each(_A_action, _A_target.functor_);
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Creates an adaptor of type sigc::retype_functor which performs C-style casts on the parameters passed on to the functor.
  * This function template specialization works on sigc::slot.
diff --git a/sigc++/adaptors/macros/retype_return.h.m4 b/sigc++/adaptors/macros/retype_return.h.m4
index 123073d..cc3e0d8 100644
--- a/sigc++/adaptors/macros/retype_return.h.m4
+++ b/sigc++/adaptors/macros/retype_return.h.m4
@@ -69,9 +69,11 @@ namespace sigc {
 template <class T_return, class T_functor>
 struct retype_return_functor : public adapts<T_functor>
 {
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
     { typedef T_return type; };
+#endif
   typedef T_return result_type;
 
   T_return operator()();
@@ -103,9 +105,11 @@ T_return retype_return_functor<T_return, T_functor>::operator()()
 template <class T_functor>
 struct retype_return_functor<void, T_functor> : public adapts<T_functor>
 {
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(class T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
     { typedef void type; };
+#endif
   typedef void result_type;
 
   void operator()();
@@ -121,7 +125,7 @@ template <class T_functor>
 void retype_return_functor<void, T_functor>::operator()()
   { this->functor_(); }
 
-  
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::retype_return_functor performs a functor on the
@@ -135,7 +139,7 @@ void visit_each(const T_action& _A_action,
 {
   visit_each(_A_action, _A_target.functor_);
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Creates an adaptor of type sigc::retype_return_functor which performs a C-style cast on the return value of the passed functor.
  * The template argument @e T_return specifies the target type of the cast.
diff --git a/sigc++/adaptors/macros/track_obj.h.m4 b/sigc++/adaptors/macros/track_obj.h.m4
index d79c6d6..18e469b 100644
--- a/sigc++/adaptors/macros/track_obj.h.m4
+++ b/sigc++/adaptors/macros/track_obj.h.m4
@@ -180,9 +180,11 @@ class track_obj_functor1 : public adapts<T_functor>
 public:
   typedef typename adapts<T_functor>::adaptor_type adaptor_type;
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   template <LOOP(typename T_arg%1=void, CALL_SIZE)>
   struct deduce_result_type
     { typedef typename adaptor_type::template deduce_result_type<LOOP(_P_(T_arg%1), CALL_SIZE)>::type type; };
+#endif
   typedef typename adaptor_type::result_type result_type;
 
   /** Constructs a track_obj_functor1 object that wraps the passed functor and
@@ -211,7 +213,9 @@ FOR(1,CALL_SIZE,[[TRACK_OBJECT_OPERATOR(%1)]])dnl
 
 FOR(2,CALL_SIZE,[[TRACK_OBJECT_FUNCTOR(%1)]])dnl
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 FOR(1,CALL_SIZE,[[TRACK_OBJECT_VISIT_EACH(%1)]])dnl
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 FOR(1,CALL_SIZE,[[TRACK_OBJECT(%1)]])dnl
 
diff --git a/sigc++/functors/macros/functor_trait.h.m4 b/sigc++/functors/macros/functor_trait.h.m4
index fcbc765..9a6052a 100644
--- a/sigc++/functors/macros/functor_trait.h.m4
+++ b/sigc++/functors/macros/functor_trait.h.m4
@@ -59,8 +59,11 @@ namespace sigc {
  * @ingroup signal
  * @ingroup slot
  */
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 struct nil;
-
+#else
+struct nil {};
+#endif
 
 /** @defgroup sigcfunctors Functors
  * Functors are copyable types that define operator()().
@@ -131,12 +134,14 @@ struct functor_trait
   typedef T_functor functor_type;
 };
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 template <class T_functor>
 struct functor_trait<T_functor,true>
 {
   typedef typename T_functor::result_type result_type;
   typedef T_functor functor_type;
 };
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** Helper macro, if you want to mix user-defined and third party functors with libsigc++.
  *
@@ -208,8 +213,10 @@ struct functor_trait<T_functor, false> \
   typedef T_functor functor_type;      \
 };
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 // detect the return type and the functor version of non-functor types.
 FOR(0,CALL_SIZE,[[FUNCTOR_PTR_FUN(%1)]])
 FOR(0,CALL_SIZE,[[FUNCTOR_MEM_FUN(%1)]])
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 } /* namespace sigc */
diff --git a/sigc++/functors/macros/mem_fun.h.m4 b/sigc++/functors/macros/mem_fun.h.m4
index 535dfd1..718a967 100644
--- a/sigc++/functors/macros/mem_fun.h.m4
+++ b/sigc++/functors/macros/mem_fun.h.m4
@@ -121,6 +121,7 @@ FOR(1, $1,[
   [$2]limit_reference<T_obj> obj_;
 };
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 //template specialization of visit_each<>(action, functor):
 /** Performs a functor on each of the targets of a functor.
  * The function overload for sigc::bound_[$2]mem_functor performs a functor
@@ -134,7 +135,7 @@ void visit_each(const T_action& _A_action,
 {
   sigc::visit_each(_A_action, _A_target.obj_);
 }
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 ])
 
 define([MEM_FUN],[dnl
diff --git a/sigc++/macros/limit_reference.h.m4 b/sigc++/macros/limit_reference.h.m4
index 25976fa..d8f0801 100644
--- a/sigc++/macros/limit_reference.h.m4
+++ b/sigc++/macros/limit_reference.h.m4
@@ -112,6 +112,7 @@ private:
   [$2]T_type& invoked;
 };
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 /** Implementation of visit_each() specialized for the [$1]limit_reference
  * class, to call visit_each() on the entity returned by the [$1]limit_reference's
  * visit() method.
@@ -127,6 +128,7 @@ visit_each(const T_action& _A_action,
 {
   visit_each(_A_action, _A_target.visit());
 }
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 ])
 
 divert(0)
diff --git a/sigc++/sigc++.h b/sigc++/sigc++.h
index 19df4f1..6cced96 100644
--- a/sigc++/sigc++.h
+++ b/sigc++/sigc++.h
@@ -35,7 +35,7 @@
  *
  * See also the 
  * <a href="http://libsigc.sourceforge.net/libsigc2/docs/manual/html/index.html">libsigc++ tutorial</a>, 
- * the <a href="http://libsigc.sourceforge.net/">the libsigc++ website</a>, and 
+ * the <a href="http://libsigc.sourceforge.net/">libsigc++ website</a>, and 
  * the <a href="http://library.gnome.org/devel/gtkmm-tutorial/unstable/chapter-signals.html">Signals appendix of the Programming with gtkmm book</a>.
  *
  * @section features Features
@@ -75,6 +75,12 @@
  * program_CPPFLAGS = $(LIBSIGC_CFLAGS)
  * program_LDADD = $(LIBSIGC_LIBS)
  * @endcode
+ *
+ * @section scope Scope of Documentation
+ *
+ * libsigc++ contains many template functions and template classes/structs,
+ * some with many specializations. This reference manual does not show all
+ * specializations of those templates that hardly any user will use directly.
  */
 
 #include <sigc++/signal.h>
diff --git a/sigc++/type_traits.h b/sigc++/type_traits.h
index ba89884..e76e89d 100644
--- a/sigc++/type_traits.h
+++ b/sigc++/type_traits.h
@@ -93,6 +93,10 @@ struct type_trait<void>
  *   thing.method_that_is_in_something();
  * }
  * @endcode
+ *
+ * sigc::is_base_and_derived<> is used internally in libsigc++. If you need such a
+ * template class elsewhere, and you have a C++11 compiler, std::is_base_of<>
+ * is recommended.
  */
 template <class T_base, class T_derived>
 struct is_base_and_derived
@@ -135,7 +139,9 @@ public:
 
 #endif //SIGC_SELF_REFERENCE_IN_MEMBER_INITIALIZATION
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   void avoid_gcc3_warning_(); //Not implemented. g++ 3.3.5 (but not 3.3.4, and not 3.4) warn that there are no public methods, even though there is a public variable.
+#endif
 };
 
 template <class T_base>
diff --git a/sigc++/visit_each.h b/sigc++/visit_each.h
index 71e4e9d..70d7522 100644
--- a/sigc++/visit_each.h
+++ b/sigc++/visit_each.h
@@ -24,6 +24,7 @@
 
 namespace sigc {
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 namespace internal {
 
 //This should really be an inner class of limit_derived_target, without the T_limit template type,
@@ -108,7 +109,7 @@ struct limit_derived_target<T_target*, T_action>
 };
 
 } /* namespace internal */
-
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 
 /** This function performs a functor on each of the targets of a functor.
  * All unknown types just call @e _A_action on them.