From 19dfcf6a33df385c2eebbd196a8c0a396f172cf1 Mon Sep 17 00:00:00 2001
From: thor <thor@35dc7657-300d-0410-a2e5-dc2837fedb53>
Date: Fri, 16 Apr 2021 12:03:40 +0000
Subject: [PATCH] doc: more doxygen in examples, less warning

git-svn-id: svn://scm.orgis.org/mpg123/trunk@4841 35dc7657-300d-0410-a2e5-dc2837fedb53
---
 doc/examples/id3dump.c          | 11 ++++++-----
 doc/examples/mpg123_to_out123.c |  3 +++
 doc/examples/mpglib.c           | 11 +++++++----
 doc/examples/scan.c             |  1 +
 4 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/doc/examples/id3dump.c b/doc/examples/id3dump.c
index 0f05173c..18bbb19f 100644
--- a/doc/examples/id3dump.c
+++ b/doc/examples/id3dump.c
@@ -10,7 +10,7 @@
 #include "stdio.h"
 #include "sys/types.h"
 
-/* Helper for v1 printing, get these strings their zero byte. */
+/** Helper for v1 printing, get these strings their zero byte. */
 void safe_print(char* name, char *data, size_t size)
 {
 	char safe[31];
@@ -21,7 +21,7 @@ void safe_print(char* name, char *data, size_t size)
 	printf("%s: %s\n", name, safe);
 }
 
-/* Print out ID3v1 info. */
+/** Print out ID3v1 info. */
 void print_v1(mpg123_id3v1 *v1)
 {
 	safe_print("Title",   v1->title,   sizeof(v1->title));
@@ -32,7 +32,7 @@ void print_v1(mpg123_id3v1 *v1)
 	printf("Genre: %i", v1->genre);
 }
 
-/* Split up a number of lines separated by \n, \r, both or just zero byte
+/** Split up a number of lines separated by \\n, \\r, both or just zero byte
    and print out each line with specified prefix. */
 void print_lines(const char* prefix, mpg123_string *inlines)
 {
@@ -75,7 +75,7 @@ void print_lines(const char* prefix, mpg123_string *inlines)
 	}
 }
 
-/* Print out the named ID3v2  fields. */
+/** Print out the named ID3v2  fields. */
 void print_v2(mpg123_id3v2 *v2)
 {
 	print_lines("Title: ",   v2->title);
@@ -86,7 +86,7 @@ void print_v2(mpg123_id3v2 *v2)
 	print_lines("Genre: ",   v2->genre);
 }
 
-/* Print out all stored ID3v2 fields with their 4-character IDs. */
+/** Print out all stored ID3v2 fields with their 4-character IDs. */
 void print_raw_v2(mpg123_id3v2 *v2)
 {
 	size_t i;
@@ -130,6 +130,7 @@ void print_raw_v2(mpg123_id3v2 *v2)
 	}
 }
 
+/** The whole operation. */
 int main(int argc, char **argv)
 {
 	int i;
diff --git a/doc/examples/mpg123_to_out123.c b/doc/examples/mpg123_to_out123.c
index b5cc8a31..bc87adc7 100644
--- a/doc/examples/mpg123_to_out123.c
+++ b/doc/examples/mpg123_to_out123.c
@@ -13,6 +13,7 @@
 #include <stdio.h>
 #include <strings.h>
 
+/** Print usage info. */
 void usage(const char *cmd)
 {
 	printf("Usage: %s <input> [<driver> [<output> [encoding [buffersize]]]]\n"
@@ -22,6 +23,7 @@ void usage(const char *cmd)
 	exit(99);
 }
 
+/** Free handles. */
 void cleanup(mpg123_handle *mh, out123_handle *ao)
 {
 	out123_del(ao);
@@ -30,6 +32,7 @@ void cleanup(mpg123_handle *mh, out123_handle *ao)
 	mpg123_delete(mh);
 }
 
+/** The whole operation. */
 int main(int argc, char *argv[])
 {
 	mpg123_handle *mh = NULL;
diff --git a/doc/examples/mpglib.c b/doc/examples/mpglib.c
index 889876ae..a5dd5a98 100644
--- a/doc/examples/mpglib.c
+++ b/doc/examples/mpglib.c
@@ -21,9 +21,10 @@
 
 #include <stdio.h>
 
-#define INBUFF  16384
-#define OUTBUFF 32768 
+#define INBUFF  16384 /**< input buffer size */
+#define OUTBUFF 32768 /**< output buffer size */
 
+/** The whole operation. */
 int main(int argc, char **argv)
 {
 	size_t size;
@@ -76,12 +77,14 @@ _setmode(_fileno(stdout),_O_BINARY);
 			mpg123_getformat(m, &rate, &channels, &enc);
 			fprintf(stderr, "New format: %li Hz, %i channels, encoding value %i\n", rate, channels, enc);
 		}
-		write(1,out,size);
+		if(write(1,out,size) != size)
+			fprintf(stderr, "Output truncated.\n");
 		outc += 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);
+			if(write(1,out,size) != size)
+				fprintf(stderr, "Output truncated.\n");
 			outc += size;
 		}
 		if(ret == MPG123_ERR){ fprintf(stderr, "some error: %s", mpg123_strerror(m)); break; }
diff --git a/doc/examples/scan.c b/doc/examples/scan.c
index e858c249..81520732 100644
--- a/doc/examples/scan.c
+++ b/doc/examples/scan.c
@@ -12,6 +12,7 @@
 #include <mpg123.h>
 #include <stdio.h>
 
+/** The whole operation. */
 int main(int argc, char **argv)
 {
 	mpg123_handle *m;