diff --git a/doc/doxy_examples.c b/doc/doxy_examples.c
new file mode 100644
index 00000000..e19ec871
--- /dev/null
+++ b/doc/doxy_examples.c
@@ -0,0 +1,17 @@
+/** \defgroup mpg123_examples example programs using libmpg123
+	@{ */
+
+/** \file mpg123_to_wav.c A simple MPEG audio to WAV converter using libmpg123 (read) and libsndfile (write).
+	...an excersize on two simple APIs.
+*/
+
+/** \file mpglib.c Example program mimicking the old mpglib test program.
+	It takes an MPEG bitstream from standard input and writes raw audio to standard output.
+	This is an use case of the mpg123_decode() in and out function in the feeder mode.
+*/
+
+/** \file scan.c Example program that examines the exact length of an MPEG file.
+	It opens a list of files and does mpg123_scan() on each and reporting the mpg123_length() before and after that.
+*/
+
+/* @} */
diff --git a/doc/doxygen.conf b/doc/doxygen.conf
index 3179d9ab..78d0c630 100644
--- a/doc/doxygen.conf
+++ b/doc/doxygen.conf
@@ -9,12 +9,13 @@ CREATE_SUBDIRS			= NO
 OUTPUT_LANGUAGE			= English
 FULL_PATH_NAMES			= NO
 
-INPUT					= ../src/libmpg123/mpg123.h
+INPUT					= doxy_examples.c examples/mpg123_to_wav.c examples/mpglib.c examples/scan.c ../src/libmpg123/mpg123.h
 OPTIMIZE_OUTPUT_FOR_C	= YES
 EXTRACT_ALL				= NO
 HIDE_UNDOC_MEMBERS		= NO
 QUIET					= YES
 WARNINGS				= YES
+SOURCE_BROWSER = YES
 
 GENERATE_HTML			= YES
 HTML_OUTPUT				= html
diff --git a/doc/examples/mpglib.c b/doc/examples/mpglib.c
index 88589ddd..fe799bb6 100644
--- a/doc/examples/mpglib.c
+++ b/doc/examples/mpglib.c
@@ -10,14 +10,14 @@
 #include <unistd.h>
 #include <stdio.h>
 
-#define INBUFF 16384
-
-unsigned char buf[INBUFF];
+#define INBUFF  16384
+#define OUTBUFF 32768 
 
 int main(int argc, char **argv)
 {
 	size_t size;
-	unsigned char out[8192];
+	unsigned char buf[INBUFF];  /* input buffer  */
+	unsigned char out[OUTBUFF]; /* output buffer */
 	ssize_t len;
 	int ret;
 	size_t in = 0, outc = 0;
@@ -30,13 +30,16 @@ int main(int argc, char **argv)
 		fprintf(stderr,"Unable to create mpg123 handle: %s\n", mpg123_plain_strerror(ret));
 		return -1;
 	}
-	mpg123_param(m, MPG123_VERBOSE, 2, 0);
-	/* mpg123_param(m, MPG123_ADD_FLAGS, MPG123_GAPLESS, 0); */
-	/* mpg123_param(m, MPG123_START_FRAME, 2300, 0); */
+	mpg123_param(m, MPG123_VERBOSE, 2, 0); /* Brabble a bit about the parsing/decoding. */
+
+	/* Now mpg123 is being prepared for feeding. The main loop will read chunks from stdin and feed them to mpg123;
+	   then take decoded data as available to write to stdout. */
 	mpg123_open_feed(m);
 	if(m == NULL) return -1;
+
 	fprintf(stderr, "Feed me some MPEG audio to stdin, I will decode to stdout.\n");
-	while(1) {
+	while(1) /* Read and write until everything is through. */
+	{
 		len = read(0,buf,INBUFF);
 		if(len <= 0)
 		{
@@ -44,8 +47,8 @@ int main(int argc, char **argv)
 			break;
 		}
 		in += len;
-		/*fprintf(stderr, ">> %lu KiB in\n", (unsigned long)in>>10);*/
-		ret = mpg123_decode(m,buf,len,out,8192,&size);
+		/* Feed input chunk and get first chunk of decoded audio. */
+		ret = mpg123_decode(m,buf,len,out,OUTBUFF,&size);
 		if(ret == MPG123_NEW_FORMAT)
 		{
 			long rate;
@@ -55,16 +58,17 @@ int main(int argc, char **argv)
 		}
 		write(1,out,size);
 		outc += size;
-		/*fprintf(stderr, "<< %lu KiB out, ret=%i\n", (unsigned long)outc>>10, ret);*/
-		while(ret != MPG123_ERR && ret != MPG123_NEED_MORE) {
-			ret = mpg123_decode(m,NULL,0,out,8192,&size);
+		while(ret != MPG123_ERR && ret != MPG123_NEED_MORE)
+		{ /* Get all decoded audio that is available now before feeding more input. */
+			ret = mpg123_decode(m,NULL,0,out,OUTBUFF,&size);
 			write(1,out,size);
 			outc += size;
-			/*fprintf(stderr, "<< %lu KiB out, ret=%i\n", (unsigned long)outc>>10, ret);*/
 		}
 		if(ret == MPG123_ERR){ fprintf(stderr, "some error: %s", mpg123_strerror(m)); break; }
 	}
 	fprintf(stderr, "%lu bytes in, %lu bytes out\n", (unsigned long)in, (unsigned long)outc);
+
+	/* Done decoding, now just clean up and leave. */
 	mpg123_delete(m);
 	mpg123_exit();
 	return 0;