Include testfsN examples in Doxygen documentation.

3 files changed, 172 insertions, 139 deletions

diff --git a/example/timefs1.c b/example/timefs1.c
index 430e00f..50363fd 100644
--- a/example/timefs1.c
+++ b/example/timefs1.c
@@ -4,50 +4,61 @@
 
   This program can be distributed under the terms of the GNU GPL.
   See the file COPYING.
+*/
 
-  This example implements a file system with a single file whose
-  contents change dynamically: it always contains the current time.
-
-  While timefs2.c uses fuse_lowlevel_notify_store() to actively push
-  the updated data into the kernel cache, this example uses
-  fuse_lowlevel_notify_inval_inode() to notify the kernel that the
-  cache has to be invalidated - but the kernel still has to explicitly
-  request the updated data on the next read.
-
-  To see the effect, first start the file system with the
-  ``--no-notify`` option:
-
-      $ timefs --update-interval=1 --no-notify mnt/
-
-  Observe that the output never changes, even though the file system
-  updates it once per second. This is because the contents are cached
-  in the kernel:
-
-      $ for i in 1 2 3 4 5; do
-      >     cat mnt/current_time
-      >     sleep 1
-      > done
-      The current time is 15:58:18
-      The current time is 15:58:18
-      The current time is 15:58:18
-      The current time is 15:58:18
-      The current time is 15:58:18
-
-  If you instead enable the notification functions, the changes become
-  visible:
-
-      $ timefs --update-interval=1 mnt/
-      $ for i in 1 2 3 4 5; do
-      >     cat mnt/current_time
-      >     sleep 1
-      > done
-      The current time is 15:58:40
-      The current time is 15:58:41
-      The current time is 15:58:42
-      The current time is 15:58:43
-      The current time is 15:58:44
+/** @file
+ * @tableofcontents
+ *
+ * This example implements a file system with a single file whose
+ * contents change dynamically: it always contains the current time.
+ *
+ * While timefs2.c uses fuse_lowlevel_notify_store() to actively push
+ *  the updated data into the kernel cache, this example uses
+ *  fuse_lowlevel_notify_inval_inode() to notify the kernel that the
+ *  cache has to be invalidated - but the kernel still has to explicitly
+ *  request the updated data on the next read.
+ *
+ *  To see the effect, first start the file system with the
+ *  ``--no-notify`` option:
+ *
+ *      $ timefs --update-interval=1 --no-notify mnt/
+ *
+ *  Observe that the output never changes, even though the file system
+ *  updates it once per second. This is because the contents are cached
+ *  in the kernel:
+ *
+ *      $ for i in 1 2 3 4 5; do
+ *      >     cat mnt/current_time
+ *      >     sleep 1
+ *      > done
+ *      The current time is 15:58:18
+ *      The current time is 15:58:18
+ *      The current time is 15:58:18
+ *      The current time is 15:58:18
+ *      The current time is 15:58:18
+ *
+ *  If you instead enable the notification functions, the changes become
+ *  visible:
+ *
+ *      $ timefs --update-interval=1 mnt/
+ *      $ for i in 1 2 3 4 5; do
+ *      >     cat mnt/current_time
+ *      >     sleep 1
+ *      > done
+ *      The current time is 15:58:40
+ *      The current time is 15:58:41
+ *      The current time is 15:58:42
+ *      The current time is 15:58:43
+ *      The current time is 15:58:44
+ *
+ * \section section_compile compiling this example
+ *
+ *     gcc -Wall timefs1.c `pkg-config fuse3 --cflags --libs` -o timefs1
+ *
+ * \section section_source the complete source
+ * \include timefs1.c
+ */
 
-*/
 
 #define FUSE_USE_VERSION 30
 
diff --git a/example/timefs2.c b/example/timefs2.c
index ea10cc1..ae3fe99 100644
--- a/example/timefs2.c
+++ b/example/timefs2.c
@@ -4,49 +4,60 @@
 
   This program can be distributed under the terms of the GNU GPL.
   See the file COPYING.
+*/
 
-  This example implements a file system with a single file whose
-  contents change dynamically: it always contains the current time.
-
-  While timefs1.c uses fuse_lowlevel_notify_inval_inode() to let the
-  kernel know that it has to invalidate the cache, this example
-  actively pushes the updated data into the kernel cache using
-  fuse_lowlevel_notify_store().
-
-  To see the effect, first start the file system with the
-  ``--no-notify`` option:
-
-      $ timefs --update-interval=1 --no-notify mnt/
-
-  Observe that the output never changes, even though the file system
-  updates it once per second. This is because the contents are cached
-  in the kernel:
-
-      $ for i in 1 2 3 4 5; do
-      >     cat mnt/current_time
-      >     sleep 1
-      > done
-      The current time is 15:58:18
-      The current time is 15:58:18
-      The current time is 15:58:18
-      The current time is 15:58:18
-      The current time is 15:58:18
-
-  If you instead enable the notification functions, the changes become
-  visible:
-
-      $ timefs --update-interval=1 mnt/
-      $ for i in 1 2 3 4 5; do
-      >     cat mnt/current_time
-      >     sleep 1
-      > done
-      The current time is 15:58:40
-      The current time is 15:58:41
-      The current time is 15:58:42
-      The current time is 15:58:43
-      The current time is 15:58:44
+/** @file
+ * @tableofcontents
+ *
+ *  This example implements a file system with a single file whose
+ *  contents change dynamically: it always contains the current time.
+ *
+ *  While timefs1.c uses fuse_lowlevel_notify_inval_inode() to let the
+ *  kernel know that it has to invalidate the cache, this example
+ *  actively pushes the updated data into the kernel cache using
+ *  fuse_lowlevel_notify_store().
+ *
+ *  To see the effect, first start the file system with the
+ *  ``--no-notify`` option:
+ *
+ *      $ timefs --update-interval=1 --no-notify mnt/
+ *
+ *  Observe that the output never changes, even though the file system
+ *  updates it once per second. This is because the contents are cached
+ *  in the kernel:
+ *
+ *      $ for i in 1 2 3 4 5; do
+ *      >     cat mnt/current_time
+ *      >     sleep 1
+ *      > done
+ *      The current time is 15:58:18
+ *      The current time is 15:58:18
+ *      The current time is 15:58:18
+ *      The current time is 15:58:18
+ *      The current time is 15:58:18
+ *
+ *  If you instead enable the notification functions, the changes become
+ *  visible:
+ *
+ *      $ timefs --update-interval=1 mnt/
+ *      $ for i in 1 2 3 4 5; do
+ *      >     cat mnt/current_time
+ *      >     sleep 1
+ *      > done
+ *      The current time is 15:58:40
+ *      The current time is 15:58:41
+ *      The current time is 15:58:42
+ *      The current time is 15:58:43
+ *      The current time is 15:58:44
+ *
+ * \section section_compile compiling this example
+ *
+ *     gcc -Wall timefs2.c `pkg-config fuse3 --cflags --libs` -o timefs2
+ *
+ * \section section_source the complete source
+ * \include timefs2.c
+ */
 
-*/
 
 #define FUSE_USE_VERSION 30
 
diff --git a/example/timefs3.c b/example/timefs3.c
index c04b81c..613407c 100644
--- a/example/timefs3.c
+++ b/example/timefs3.c
@@ -4,64 +4,75 @@
 
   This program can be distributed under the terms of the GNU GPL.
   See the file COPYING.
+*/
 
-  This example implements a file system with a single file whose
-  file name changes dynamically to reflect the current time.
-
-  It illustrates the use of the fuse_lowlevel_notify_inval_entry()
-  function.
-
-  To see the effect, first start the file system with the
-  ``--no-notify``
-
-      $ timefs --update-interval=1 --timeout 30 --no-notify mnt/
-
-  Observe that `ls` always prints the correct directory contents
-  (since `readdir` output is not cached)::
-
-      $ ls mnt; sleep 1; ls mnt; sleep 1; ls mnt
-      Time_is_15h_48m_33s  current_time
-      Time_is_15h_48m_34s  current_time
-      Time_is_15h_48m_35s  current_time
-
-  However, if you try to access a file by name the kernel will
-  report that it still exists:
-
-      $ file=$(ls mnt/); echo $file
-      Time_is_15h_50m_09s
-      $ sleep 5; stat mnt/$file
-        File: ‘mnt/Time_is_15h_50m_09s’
-        Size: 32                Blocks: 0          IO Block: 4096   regular file
-      Device: 2ah/42d	Inode: 3           Links: 1
-      Access: (0444/-r--r--r--)  Uid: (    0/    root)   Gid: (    0/    root)
-      Access: 1969-12-31 16:00:00.000000000 -0800
-      Modify: 1969-12-31 16:00:00.000000000 -0800
-      Change: 1969-12-31 16:00:00.000000000 -0800
-       Birth: -
-
-  Only once the kernel cache timeout has been reached will the stat
-  call fail:
-
-      $ sleep 30; stat mnt/$file
-      stat: cannot stat ‘mnt/Time_is_15h_50m_09s’: No such file or directory
-
-  In contrast, if you enable notifications you will be unable to stat
-  the file as soon as the file system updates its name:
-
-      $ timefs --update-interval=1 --timeout 30 --no-notify mnt/
-      $ file=$(ls mnt/); stat mnt/$file
-        File: ‘mnt/Time_is_20h_42m_11s’
-        Size: 0                 Blocks: 0          IO Block: 4096   regular empty file
-      Device: 2ah/42d	Inode: 2           Links: 1
-      Access: (0000/----------)  Uid: (    0/    root)   Gid: (    0/    root)
-      Access: 1969-12-31 16:00:00.000000000 -0800
-      Modify: 1969-12-31 16:00:00.000000000 -0800
-      Change: 1969-12-31 16:00:00.000000000 -0800
-       Birth: -
-      $ sleep 1; stat mnt/$file
-      stat: cannot stat ‘mnt/Time_is_20h_42m_11s’: No such file or directory
+/** @file
+ * @tableofcontents
+ *
+ * This example implements a file system with a single file whose
+ * file name changes dynamically to reflect the current time.
+ *
+ * It illustrates the use of the fuse_lowlevel_notify_inval_entry()
+ * function.
+ *
+ * To see the effect, first start the file system with the
+ * ``--no-notify``
+ *
+ *     $ timefs --update-interval=1 --timeout 30 --no-notify mnt/
+ *
+ * Observe that `ls` always prints the correct directory contents
+ * (since `readdir` output is not cached)::
+ *
+ *     $ ls mnt; sleep 1; ls mnt; sleep 1; ls mnt
+ *     Time_is_15h_48m_33s  current_time
+ *     Time_is_15h_48m_34s  current_time
+ *     Time_is_15h_48m_35s  current_time
+ *
+ * However, if you try to access a file by name the kernel will
+ * report that it still exists:
+ *
+ *     $ file=$(ls mnt/); echo $file
+ *     Time_is_15h_50m_09s
+ *     $ sleep 5; stat mnt/$file
+ *       File: ‘mnt/Time_is_15h_50m_09s’
+ *       Size: 32                Blocks: 0          IO Block: 4096   regular file
+ *     Device: 2ah/42d	Inode: 3           Links: 1
+ *     Access: (0444/-r--r--r--)  Uid: (    0/    root)   Gid: (    0/    root)
+ *     Access: 1969-12-31 16:00:00.000000000 -0800
+ *     Modify: 1969-12-31 16:00:00.000000000 -0800
+ *     Change: 1969-12-31 16:00:00.000000000 -0800
+ *      Birth: -
+ *
+ * Only once the kernel cache timeout has been reached will the stat
+ * call fail:
+ *
+ *     $ sleep 30; stat mnt/$file
+ *     stat: cannot stat ‘mnt/Time_is_15h_50m_09s’: No such file or directory
+ *
+ * In contrast, if you enable notifications you will be unable to stat
+ * the file as soon as the file system updates its name:
+ *
+ *     $ timefs --update-interval=1 --timeout 30 --no-notify mnt/
+ *     $ file=$(ls mnt/); stat mnt/$file
+ *       File: ‘mnt/Time_is_20h_42m_11s’
+ *       Size: 0                 Blocks: 0          IO Block: 4096   regular empty file
+ *     Device: 2ah/42d	Inode: 2           Links: 1
+ *     Access: (0000/----------)  Uid: (    0/    root)   Gid: (    0/    root)
+ *     Access: 1969-12-31 16:00:00.000000000 -0800
+ *     Modify: 1969-12-31 16:00:00.000000000 -0800
+ *     Change: 1969-12-31 16:00:00.000000000 -0800
+ *      Birth: -
+ *     $ sleep 1; stat mnt/$file
+ *     stat: cannot stat ‘mnt/Time_is_20h_42m_11s’: No such file or directory
+ *
+ * \section section_compile compiling this example
+ *
+ *     gcc -Wall timefs3.c `pkg-config fuse3 --cflags --libs` -o timefs3
+ *
+ * \section section_source the complete source
+ * \include timefs3.c
+ */
 
-*/
 
 #define FUSE_USE_VERSION 30