[libsigc++2] Add main page to Doxygen documentation

[David King <davidk src gnome org>]

commit a35d1d92bda4a1fbbd23ed9221a6d729cef7dc33
Author: David King <davidk openismus com>
Date:   Fri Apr 23 12:09:46 2010 +0200

    Add main page to Doxygen documentation
    
    * docs/Makefile.am: Parse sigc++/sigc++.h for documentation.
    * sigc++/sigc++.h: Add main page to Doxygen documentation.

 ChangeLog        |    7 +++++++
 docs/Makefile.am |    3 ++-
 sigc++/sigc++.h  |   54 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 62 insertions(+), 2 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 800f884..e38f353 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2010-04-23  David King  <davidk openismus com>
 
+	Add main page to Doxygen documentation
+
+	* docs/Makefile.am: Parse sigc++/sigc++.h for documentation.
+	* sigc++/sigc++.h: Add main page to Doxygen documentation.
+
+2010-04-23  David King  <davidk openismus com>
+
 	Fix the functors Doxygen group in the m4 files
 
 	* sigc++/functors/macros/functor_trait.h.m4:
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 34517da..aec4527 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -26,7 +26,8 @@ book_name = libsigc++-$(SIGCXX_API_VERSION)
 libsigc_h = $(sigc_public_h) $(sigc_built_h)
 vp_select = $(or $(wildcard $(top_builddir)/sigc++/$(file)),$(top_srcdir)/sigc++/$(file))
 vp_search = $(foreach file,$(libsigc_h),$(vp_select))
-doc_input = $(if $(srcdir:.=),$(vp_search),$(addprefix $(top_builddir)/sigc++/,$(libsigc_h)))
+doc_input = $(if $(srcdir:.=),$(vp_search),$(addprefix $(top_builddir)/sigc++/,$(libsigc_h))) \
+            $(top_srcdir)/sigc++/sigc++.h
 
 include $(top_srcdir)/build/doc-reference.am
 
diff --git a/sigc++/sigc++.h b/sigc++/sigc++.h
index 90a9e6d..df63375 100644
--- a/sigc++/sigc++.h
+++ b/sigc++/sigc++.h
@@ -20,6 +20,59 @@
 #ifndef SIGCXX_SIGCXX_H
 #define SIGCXX_SIGCXX_H
 
+/** @mainpage libsigc++ Reference Manual
+ *
+ * @section description Description
+ *
+ * libsigc++ implements a typesafe callback system for standard C++. It allows
+ * you to define signals and to connect those signals to any callback function,
+ * either a global or a member function, regardless of whether it is static or
+ * virtual. It also contains adaptor classes for connection of dissimilar
+ * callbacks and has an ease of use unmatched by other C++ callback libraries.
+ *
+ * For instance, see @ref adaptors "Adaptors", @ref sigcfunctors "Functors",
+ * @ref lambdas "Lambdas", @ref signal "Signals" and @ref slot "Slots".
+ *
+ * See also the libsigc++ website: http://libsigc.sourceforge.net/
+ *
+ * @section features Features
+ *
+ * - Compile time typesafe callbacks (faster than run time checks)
+ * - Typesafety violations report line number correctly with template names (no
+ *   tracing template failures into headers)
+ * - No compiler extensions or meta compilers required
+ * - Proper handling of dynamic objects and signals (deleted objects will not
+ *   cause seg faults)
+ * - Extendable API at any level: signal, slot, connection and trackable
+ * - Extensions do not require alteration of basic components
+ * - User definable accumulators
+ * - A variety of adaptors to change the callback signature: bind, hide,
+ *   retype, compose and lambda call groups
+ *
+ * @section basics Basic usage
+ *
+ * Include the libsigc++ header:
+ * @code
+ * #include <sigc++/sigc++.h>
+ * @endcode
+ * This includes every header installed by libsigc++, so can slow down
+ * compilation, but suffices for this simple example. Assuming that your
+ * program source file is @c program.cc, compile it with:
+ * @code
+ * g++ program.cc -o program `pkg-config --cflags --libs sigc++-2.0`
+ * @endcode
+ * Alternatively, if using autoconf, use the following in @c configure.ac:
+ * @code
+ * PKG_CHECK_MODULES([LIBSIGCXX], [sigc++-2.0])
+ * @endcode
+ * Then use the generated @c LIBSIGCXX_CFLAGS and @c LIBSIGCXX_LIBS variables
+ * in the project @c Makefile.am files. For example:
+ * @code
+ * program_CPPFLAGS = $(LIBSIGCXX_CFLAGS)
+ * program_LDADD = $(LIBSIGCXX_LIBS)
+ * @endcode
+ */
+
 #include <sigc++/signal.h>
 #include <sigc++/connection.h>
 #include <sigc++/trackable.h>
@@ -27,4 +80,3 @@
 #include <sigc++/functors/functors.h>
 
 #endif /* SIGCXX_SIGCXX_H */
-