diff --git a/ChangeLog b/ChangeLog
index 70baf7c667..97e785b2c5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2005-12-12  Julien MOUTTE  <julien@moutte.net>
+
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-good-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-good-plugins-sections.txt:
+	* docs/plugins/gst-plugins-good-plugins.hierarchy:
+	* gst/videomixer/videomixer.c: (gst_videomixer_pad_sink_setcaps),
+	(gst_videomixer_getcaps), (gst_videomixer_fill_queues),
+	(gst_videomixer_update_queues), (gst_videomixer_collected): Adding
+	documentation for videomixer on my way with a funny sample
+	pipeline.
+
 2005-12-12  Julien MOUTTE  <julien@moutte.net>
 
 	* gst/videomixer/videomixer.c: (gst_videomixer_pad_sink_setcaps),
diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index 67a90f36e1..ddc8062301 100644
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -81,7 +81,8 @@ EXTRA_HFILES = \
 	$(top_srcdir)/ext/cairo/gsttimeoverlay.h \
 	$(top_srcdir)/ext/flac/gstflacdec.h \
 	$(top_srcdir)/gst/multipart/multipartmux.c \
-	$(top_srcdir)/gst/multipart/multipartdemux.c
+	$(top_srcdir)/gst/multipart/multipartdemux.c \
+	$(top_srcdir)/gst/videomixer/videomixer.c
 
 # example code that needs to be converted to xml and placed in xml/
 EXAMPLE_CFILES = \
diff --git a/docs/plugins/gst-plugins-good-plugins-docs.sgml b/docs/plugins/gst-plugins-good-plugins-docs.sgml
index a6df6a46e3..731225d0d0 100644
--- a/docs/plugins/gst-plugins-good-plugins-docs.sgml
+++ b/docs/plugins/gst-plugins-good-plugins-docs.sgml
@@ -20,6 +20,7 @@
     <xi:include href="xml/element-level.xml" />
     <xi:include href="xml/element-multipartmux.xml" />
     <xi:include href="xml/element-multipartdemux.xml" />
+    <xi:include href="xml/element-videomixer.xml" />
   </chapter>
 
   <chapter>
diff --git a/docs/plugins/gst-plugins-good-plugins-sections.txt b/docs/plugins/gst-plugins-good-plugins-sections.txt
index 70a431c07b..8cfbfd5780 100644
--- a/docs/plugins/gst-plugins-good-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-good-plugins-sections.txt
@@ -62,3 +62,12 @@ GstMultipartDemux
 GstMultipartDemuxClass
 </SECTION>
 
+<SECTION>
+<FILE>element-videomixer</FILE>
+GstVideoMixer
+GstVideoMixerBackground
+<TITLE>videomixer</TITLE>
+<SUBSECTION Standard>
+GstVideoMixerClass
+</SECTION>
+
diff --git a/docs/plugins/gst-plugins-good-plugins.hierarchy b/docs/plugins/gst-plugins-good-plugins.hierarchy
index e3db900e6f..a1cfacce77 100644
--- a/docs/plugins/gst-plugins-good-plugins.hierarchy
+++ b/docs/plugins/gst-plugins-good-plugins.hierarchy
@@ -294,6 +294,7 @@ GObject
       GstTypeFindElement
       GstMultipartMux
       GstMultipartDemux
+      GstVideoMixer
     GstPadTemplate
     GstIndex
       GstMemIndex
diff --git a/gst/videomixer/videomixer.c b/gst/videomixer/videomixer.c
index 5093000e6b..f4b6b13bda 100644
--- a/gst/videomixer/videomixer.c
+++ b/gst/videomixer/videomixer.c
@@ -17,6 +17,34 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-videomixer
+ * @short_description: Takes several AYUV video streams as input and mixes them
+ * together.
+ *
+ * <refsect2>
+ * <para>
+ * Videomixer can only accept AYUV video streams. For each of the requested
+ * sink pads it will compare the incoming geometry and framerate to define the
+ * output parameters. Indeed output video frames will have the geometry of the
+ * biggest incoming video stream and the framerate of the fastest incoming one.
+ * </para>
+ * <title>Sample pipelines</title>
+ * <para>
+ * Here is a pipeline to demonstrate videomixer used together with videobox :
+ * <programlisting>
+ * gst-launch videotestsrc pattern=1 ! video/x-raw-yuv, framerate=\(fraction\)10/1, width=100, height=100 ! videobox border-alpha=0 alpha=0.5 top=-70 bottom=-70 right=-220 ! videomixer name=mix ! ffmpegcolorspace ! xvimagesink videotestsrc ! video/x-raw-yuv, framerate=\(fraction\)5/1, width=320, height=240 ! alpha alpha=0.7 ! mix.
+ * </programlisting>
+ * This should show a 320x240 pixels video test source with some transparency
+ * showing the background checker pattern. Another video test source with just
+ * the snow pattern of 100x100 pixels is overlayed on top of the first one on
+ * the left vertically centered with a small transparency showing the first
+ * video test source behind and the checker pattern under it. Note that the
+ * framerate of the output video is 10 frames per second.
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -228,8 +256,13 @@ gst_videomixer_pad_set_property (GObject * object, guint prop_id,
 }
 
 /**
-  * GstVideoMixerBackground:
-  */
+ * GstVideoMixerBackground:
+ * @VIDEO_MIXER_BACKGROUND_CHECKER: checker pattern background
+ * @VIDEO_MIXER_BACKGROUND_BLACK: solid color black background
+ * @VIDEO_MIXER_BACKGROUND_WHITE: solid color white background
+ *
+ * The different backgrounds videomixer can blend over.
+ */
 typedef enum
 {
   VIDEO_MIXER_BACKGROUND_CHECKER,
@@ -238,6 +271,11 @@ typedef enum
 }
 GstVideoMixerBackground;
 
+/**
+ * GstVideoMixer:
+ *
+ * The opaque #GstVideoMixer structure.
+ */
 struct _GstVideoMixer
 {
   GstElement element;