examples: apply doxy entries consistency fixes

Use consistent format for the @file field and file description.

23 files changed, 95 insertions, 84 deletions

diff --git a/doc/examples/avio_http_serve_files.c b/doc/examples/avio_http_serve_files.c
index d6a1d146f3..2aae3870c2 100644
--- a/doc/examples/avio_http_serve_files.c
+++ b/doc/examples/avio_http_serve_files.c
@@ -21,12 +21,11 @@
  */
 
 /**
- * @file
- * libavformat multi-client network API usage example.
- *
+ * @file libavformat multi-client network API usage example
  * @example avio_http_serve_files.c
- * This example will serve a file without decoding or demuxing it over http.
- * Multiple clients can connect and will receive the same file.
+ *
+ * Serve a file without decoding or demuxing it over the HTTP protocol. Multiple
+ * clients can connect and will receive the same file.
  */
 
 #include <libavformat/avformat.h>
diff --git a/doc/examples/avio_list_dir.c b/doc/examples/avio_list_dir.c
index 3073baaefa..bb19debad3 100644
--- a/doc/examples/avio_list_dir.c
+++ b/doc/examples/avio_list_dir.c
@@ -20,6 +20,13 @@
  * THE SOFTWARE.
  */
 
+/**
+ * @file libavformat AVIOContext list directory API usage example
+ * @example avio_list_dir.c
+ *
+ * Show how to list directories through the libavformat AVIOContext API.
+ */
+
 #include <libavcodec/avcodec.h>
 #include <libavformat/avformat.h>
 #include <libavformat/avio.h>
diff --git a/doc/examples/avio_read_callback.c b/doc/examples/avio_read_callback.c
index e57a66bdec..4cf81ad72e 100644
--- a/doc/examples/avio_read_callback.c
+++ b/doc/examples/avio_read_callback.c
@@ -21,12 +21,11 @@
  */
 
 /**
- * @file
- * libavformat AVIOContext API example.
+ * @file libavformat AVIOContext read callback API usage example
+ * @example avio_read_callback.c
  *
  * Make libavformat demuxer access media content through a custom
  * AVIOContext read callback.
- * @example avio_read_callback.c
  */
 
 #include <libavcodec/avcodec.h>
diff --git a/doc/examples/decode_audio.c b/doc/examples/decode_audio.c
index 49ad22cba6..bcb3d87a69 100644
--- a/doc/examples/decode_audio.c
+++ b/doc/examples/decode_audio.c
@@ -21,10 +21,11 @@
  */
 
 /**
- * @file
- * audio decoding with libavcodec API example
- *
+ * @file libavcodec audio decoding API usage example
  * @example decode_audio.c
+ *
+ * Decode data from an MP2 input file and generate a raw audio file to
+ * be played with ffplay.
  */
 
 #include <stdio.h>
diff --git a/doc/examples/decode_filter_audio.c b/doc/examples/decode_filter_audio.c
index 607237bf11..2046419819 100644
--- a/doc/examples/decode_filter_audio.c
+++ b/doc/examples/decode_filter_audio.c
@@ -23,9 +23,11 @@
  */
 
 /**
- * @file
- * API example for audio decoding and filtering
+ * @file audio decoding and filtering usage example
  * @example decode_filter_audio.c
+ *
+ * Demux, decode and filter audio input file, generate a raw audio
+ * file to be played with ffplay.
  */
 
 #include <unistd.h>
diff --git a/doc/examples/decode_video.c b/doc/examples/decode_video.c
index 7238e38103..81ec4b50e2 100644
--- a/doc/examples/decode_video.c
+++ b/doc/examples/decode_video.c
@@ -21,10 +21,11 @@
  */
 
 /**
- * @file
- * video decoding with libavcodec API example
+ * @file libavcodec video decoding API usage example
+ * @example decode_video.c *
  *
- * @example decode_video.c
+ * Read from an MPEG1 video file, decode frames, and generate PGM images as
+ * output.
  */
 
 #include <stdio.h>
diff --git a/doc/examples/demux_decode.c b/doc/examples/demux_decode.c
index a2ca53b26b..ebef7a6114 100644
--- a/doc/examples/demux_decode.c
+++ b/doc/examples/demux_decode.c
@@ -21,12 +21,12 @@
  */
 
 /**
- * @file
- * libavformat and libavcodec API example to demux and decode.
- *
- * Show how to use the libavformat and libavcodec API to demux and
- * decode audio and video data.
+ * @file libavformat and libavcodec demuxing and decoding API usage example
  * @example demux_decode.c
+ *
+ * Show how to use the libavformat and libavcodec API to demux and decode audio
+ * and video data. Write the output as raw audio and input files to be played by
+ * ffplay.
  */
 
 #include <libavutil/imgutils.h>
diff --git a/doc/examples/encode_audio.c b/doc/examples/encode_audio.c
index 9a1792b725..bb16683d94 100644
--- a/doc/examples/encode_audio.c
+++ b/doc/examples/encode_audio.c
@@ -21,10 +21,10 @@
  */
 
 /**
- * @file
- * audio encoding with libavcodec API example.
- *
+ * @file libavcodec encoding audio API usage examples
  * @example encode_audio.c
+ *
+ * Generate a synthetic audio signal and encode it to an output MP2 file.
  */
 
 #include <stdint.h>
diff --git a/doc/examples/encode_video.c b/doc/examples/encode_video.c
index 6c3a3f5684..4fae146f2e 100644
--- a/doc/examples/encode_video.c
+++ b/doc/examples/encode_video.c
@@ -21,10 +21,10 @@
  */
 
 /**
- * @file
- * video encoding with libavcodec API example
- *
+ * @file libavcodec encoding video API usage example
  * @example encode_video.c
+ *
+ * Generate synthetic video data and encode it to an output file.
  */
 
 #include <stdio.h>
diff --git a/doc/examples/extract_mvs.c b/doc/examples/extract_mvs.c
index b80ba26bb7..5603064d72 100644
--- a/doc/examples/extract_mvs.c
+++ b/doc/examples/extract_mvs.c
@@ -21,6 +21,14 @@
  * THE SOFTWARE.
  */
 
+/**
+ * @file libavcodec motion vectors extraction API usage example
+ * @example extract_mvs.c
+ *
+ * Read from input file, decode video stream and print a motion vectors
+ * representation to stdout.
+ */
+
 #include <libavutil/motion_vector.h>
 #include <libavcodec/avcodec.h>
 #include <libavformat/avformat.h>
diff --git a/doc/examples/filter_audio.c b/doc/examples/filter_audio.c
index f53e52562b..9e4039b900 100644
--- a/doc/examples/filter_audio.c
+++ b/doc/examples/filter_audio.c
@@ -19,13 +19,11 @@
  */
 
 /**
- * @file
- * libavfilter API usage example.
- *
+ * @file libavfilter audio filtering API usage example
  * @example filter_audio.c
- * This example will generate a sine wave audio,
- * pass it through a simple filter chain, and then compute the MD5 checksum of
- * the output data.
+ *
+ * This example will generate a sine wave audio, pass it through a simple filter
+ * chain, and then compute the MD5 checksum of the output data.
  *
  * The filter chain it uses is:
  * (input) -> abuffer -> volume -> aformat -> abuffersink -> (output)
diff --git a/doc/examples/hw_decode.c b/doc/examples/hw_decode.c
index 0d23f451e6..6a4a4fb83d 100644
--- a/doc/examples/hw_decode.c
+++ b/doc/examples/hw_decode.c
@@ -24,12 +24,11 @@
  */
 
 /**
- * @file
- * HW-Accelerated decoding example.
- *
+ * @file HW-accelerated decoding API usage.example
  * @example hw_decode.c
- * This example shows how to do HW-accelerated decoding with output
- * frames from the HW video surfaces.
+ *
+ * Perform HW-accelerated decoding with output frames from HW video
+ * surfaces.
  */
 
 #include <stdio.h>
diff --git a/doc/examples/mux.c b/doc/examples/mux.c
index e3062c5003..d1f682e196 100644
--- a/doc/examples/mux.c
+++ b/doc/examples/mux.c
@@ -21,12 +21,11 @@
  */
 
 /**
- * @file
- * libavformat API example.
- *
- * Output a media file in any supported libavformat format. The default
- * codecs are used.
+ * @file libavformat muxing API usage example
  * @example mux.c
+ *
+ * Generate a synthetic audio and video signal and mux them to a media file in
+ * any supported libavformat format. The default codecs are used.
  */
 
 #include <stdlib.h>
diff --git a/doc/examples/qsv_decode.c b/doc/examples/qsv_decode.c
index 0cdef4466c..cc2662d5bd 100644
--- a/doc/examples/qsv_decode.c
+++ b/doc/examples/qsv_decode.c
@@ -21,12 +21,11 @@
  */
 
 /**
- * @file
- * Intel QSV-accelerated H.264 decoding example.
- *
+ * @file Intel QSV-accelerated H.264 decoding API usage example
  * @example qsv_decode.c
- * This example shows how to do QSV-accelerated H.264 decoding with output
- * frames in the GPU video surfaces.
+ *
+ * Perform QSV-accelerated H.264 decoding with output frames in the
+ * GPU video surfaces, write the decoded frames to an output file.
  */
 
 #include "config.h"
diff --git a/doc/examples/qsv_transcode.c b/doc/examples/qsv_transcode.c
index 9b37bbea9f..7ea3ef5674 100644
--- a/doc/examples/qsv_transcode.c
+++ b/doc/examples/qsv_transcode.c
@@ -1,6 +1,4 @@
 /*
- * Quick Sync Video (video transcoding) transcode sample
- *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
  * in the Software without restriction, including without limitation the rights
@@ -21,12 +19,12 @@
  */
 
 /**
- * @file
- * Intel QSV-accelerated transcoding example.
- *
+ * @file Intel QSV-accelerated video transcoding API usage example
  * @example qsv_transcode.c
- * This example shows how to do QSV-accelerated transcoding and how to
- * dynamically change encoder's option.
+ *
+ * Perform QSV-accelerated transcoding and show to dynamically change
+ * encoder's options.
+ *
  * Usage: qsv_transcode input_stream codec output_stream initial option
  *                      { frame_number new_option }
  * e.g: - qsv_transcode input.mp4 h264_qsv output_h264.mp4 "g 60"
diff --git a/doc/examples/remux.c b/doc/examples/remux.c
index 8855199c60..ecf30489f1 100644
--- a/doc/examples/remux.c
+++ b/doc/examples/remux.c
@@ -21,11 +21,11 @@
  */
 
 /**
- * @file
- * libavformat/libavcodec demuxing and muxing API example.
- *
- * Remux streams from one container format to another.
+ * @file libavformat/libavcodec demuxing and muxing API usage example
  * @example remux.c
+ *
+ * Remux streams from one container format to another. Data is copied from the
+ * input to the output without transcoding.
  */
 
 #include <libavutil/timestamp.h>
diff --git a/doc/examples/resample_audio.c b/doc/examples/resample_audio.c
index 890d30c934..db9b4e5e08 100644
--- a/doc/examples/resample_audio.c
+++ b/doc/examples/resample_audio.c
@@ -21,8 +21,12 @@
  */
 
 /**
+ * @file audio resampling API usage example
  * @example resample_audio.c
- * libswresample API use example.
+ *
+ * Generate a synthetic audio signal, and Use libswresample API to perform audio
+ * resampling. The output is written to a raw audio file to be played with
+ * ffplay.
  */
 
 #include <libavutil/opt.h>
diff --git a/doc/examples/scale_video.c b/doc/examples/scale_video.c
index 27cd00996d..cb4da4a576 100644
--- a/doc/examples/scale_video.c
+++ b/doc/examples/scale_video.c
@@ -21,9 +21,10 @@
  */
 
 /**
- * @file
- * libswscale API use example.
+ * @file libswscale API usage example
  * @example scale_video.c
+ *
+ * Generate a synthetic video signal and use libswscale to perform rescaling.
  */
 
 #include <libavutil/imgutils.h>
diff --git a/doc/examples/show_metadata.c b/doc/examples/show_metadata.c
index f7f07bf598..abe3cc0cae 100644
--- a/doc/examples/show_metadata.c
+++ b/doc/examples/show_metadata.c
@@ -21,9 +21,10 @@
  */
 
 /**
- * @file
- * Shows how the metadata API can be used in application programs.
+ * @file libavformat metadata extraction API usage example
  * @example show_metadata.c
+ *
+ * Show metadata from an input file.
  */
 
 #include <stdio.h>
diff --git a/doc/examples/transcode.c b/doc/examples/transcode.c
index b0f4fb0399..805a028ed7 100644
--- a/doc/examples/transcode.c
+++ b/doc/examples/transcode.c
@@ -23,9 +23,11 @@
  */
 
 /**
- * @file
- * API example for demuxing, decoding, filtering, encoding and muxing
+ * @file demuxing, decoding, filtering, encoding and muxing API usage example
  * @example transcode.c
+ *
+ * Convert input to output file, applying some hard-coded filter-graph on both
+ * audio and video streams.
  */
 
 #include <libavcodec/avcodec.h>
diff --git a/doc/examples/transcode_aac.c b/doc/examples/transcode_aac.c
index 2d4f9a59d3..bb5681a7c0 100644
--- a/doc/examples/transcode_aac.c
+++ b/doc/examples/transcode_aac.c
@@ -19,12 +19,11 @@
  */
 
 /**
- * @file
- * Simple audio converter
- *
+ * @file audio transcoding to MPEG/AAC API usage example
  * @example transcode_aac.c
- * Convert an input audio file to AAC in an MP4 container using FFmpeg.
- * Formats other than MP4 are supported based on the output file extension.
+ *
+ * Convert an input audio file to AAC in an MP4 container. Formats other than
+ * MP4 are supported based on the output file extension.
  * @author Andreas Unterweger (dustsigns@gmail.com)
  */
 
diff --git a/doc/examples/vaapi_encode.c b/doc/examples/vaapi_encode.c
index e232fa579a..d5f472f6dd 100644
--- a/doc/examples/vaapi_encode.c
+++ b/doc/examples/vaapi_encode.c
@@ -1,6 +1,4 @@
 /*
- * Video Acceleration API (video encoding) encode sample
- *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
  * in the Software without restriction, including without limitation the rights
@@ -21,13 +19,12 @@
  */
 
 /**
- * @file
- * Intel VAAPI-accelerated encoding example.
- *
+ * @file Intel VAAPI-accelerated encoding API usage example
  * @example vaapi_encode.c
- * This example shows how to do VAAPI-accelerated encoding. now only support NV12
- * raw file, usage like: vaapi_encode 1920 1080 input.yuv output.h264
  *
+ * Perform VAAPI-accelerated encoding. Read input from an NV12 raw
+ * file, and write the H.264 encoded data to an output raw file.
+ * Usage: vaapi_encode 1920 1080 input.yuv output.h264
  */
 
 #include <stdio.h>
diff --git a/doc/examples/vaapi_transcode.c b/doc/examples/vaapi_transcode.c
index a174bb643a..8367cb3040 100644
--- a/doc/examples/vaapi_transcode.c
+++ b/doc/examples/vaapi_transcode.c
@@ -1,6 +1,4 @@
 /*
- * Video Acceleration API (video transcoding) transcode sample
- *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
  * in the Software without restriction, including without limitation the rights
@@ -21,11 +19,10 @@
  */
 
 /**
- * @file
- * Intel VAAPI-accelerated transcoding example.
- *
+ * @file Intel VAAPI-accelerated transcoding API usage example
  * @example vaapi_transcode.c
- * This example shows how to do VAAPI-accelerated transcoding.
+ *
+ * Perform VAAPI-accelerated transcoding.
  * Usage: vaapi_transcode input_stream codec output_stream
  * e.g: - vaapi_transcode input.mp4 h264_vaapi output_h264.mp4
  *      - vaapi_transcode input.mp4 vp9_vaapi output_vp9.ivf