From: Karel Zak <kzak@redhat.com>
Date: Thu, 8 Sep 2022 11:08:15 +0000 (+0200)
Subject: libmount: cleanup comments for hooks
X-Git-Tag: v2.39-rc1~269
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7f014edac3acdbc0d408f77a3fd431345814d970;p=thirdparty%2Futil-linux.git

libmount: cleanup comments for hooks

Signed-off-by: Karel Zak <kzak@redhat.com>
---

diff --git a/libmount/src/hook_idmap.c b/libmount/src/hook_idmap.c
index 29f34700cc..1718679457 100644
--- a/libmount/src/hook_idmap.c
+++ b/libmount/src/hook_idmap.c
@@ -12,6 +12,8 @@
  *
  *
  * This is X-mount.idmap= implementation.
+ *
+ * Please, see the comment in libmount/src/hooks.c to understand how hooks work.
  */
 #include <stdbool.h>
 #include <sys/socket.h>
diff --git a/libmount/src/hook_loopdev.c b/libmount/src/hook_loopdev.c
index 652ae76377..22379cf72d 100644
--- a/libmount/src/hook_loopdev.c
+++ b/libmount/src/hook_loopdev.c
@@ -8,12 +8,9 @@
  * under the terms of the GNU Lesser General Public License as published by
  * the Free Software Foundation; either version 2.1 of the License, or
  * (at your option) any later version.
+ *
+ * Please, see the comment in libmount/src/hooks.c to understand how hooks work.
  */
-
-/*
- * DOCS: - "lo@" prefix for fstype is unsupported
- */
-
 #include <blkid.h>
 #include <stdbool.h>
 
diff --git a/libmount/src/hook_mkdir.c b/libmount/src/hook_mkdir.c
index bd8a083030..6e4d736638 100644
--- a/libmount/src/hook_mkdir.c
+++ b/libmount/src/hook_mkdir.c
@@ -8,8 +8,10 @@
  * under the terms of the GNU Lesser General Public License as published by
  * the Free Software Foundation; either version 2.1 of the License, or
  * (at your option) any later version.
+ *
+ *
+ * Please, see the comment in libmount/src/hooks.c to understand how hooks work.
  */
-
 #include "mountP.h"
 #include "fileutils.h"
 
diff --git a/libmount/src/hook_mount_legacy.c b/libmount/src/hook_mount_legacy.c
index 7468f31f93..8b082f2abe 100644
--- a/libmount/src/hook_mount_legacy.c
+++ b/libmount/src/hook_mount_legacy.c
@@ -8,6 +8,11 @@
  * under the terms of the GNU Lesser General Public License as published by
  * the Free Software Foundation; either version 2.1 of the License, or
  * (at your option) any later version.
+ *
+ *
+ * This is classic mount(2) based mount.
+ *
+ * Please, see the comment in libmount/src/hooks.c to understand how hooks work.
  */
 
 #include "mountP.h"
diff --git a/libmount/src/hook_owner.c b/libmount/src/hook_owner.c
index 02fdcbefd9..9c23733a38 100644
--- a/libmount/src/hook_owner.c
+++ b/libmount/src/hook_owner.c
@@ -11,8 +11,9 @@
  *
  *
  * This is X-mount.owner=, X-mount.group= and X-mount.mode= implementation.
+ *
+ * Please, see the comment in libmount/src/hooks.c to understand how hooks work.
  */
-
 #include <sched.h>
 
 #include "mountP.h"
diff --git a/libmount/src/hook_subdir.c b/libmount/src/hook_subdir.c
index 34b680b3fa..d0a274bc70 100644
--- a/libmount/src/hook_subdir.c
+++ b/libmount/src/hook_subdir.c
@@ -12,8 +12,9 @@
  *
  * This is X-mount.subdir= implementation. The code uses global hookset data
  * rather than per-callback (hook) data.
+ *
+ * Please, see the comment in libmount/src/hooks.c to understand how hooks work.
  */
-
 #include <sched.h>
 
 #include "mountP.h"
diff --git a/libmount/src/hook_veritydev.c b/libmount/src/hook_veritydev.c
index 8f2386539c..f91778ad95 100644
--- a/libmount/src/hook_veritydev.c
+++ b/libmount/src/hook_veritydev.c
@@ -9,8 +9,10 @@
  * under the terms of the GNU Lesser General Public License as published by
  * the Free Software Foundation; either version 2.1 of the License, or
  * (at your option) any later version.
+ *
+ *
+ * Please, see comment in libmount/src/hooks.c to understand how hooks work.
  */
-
 #include "mountP.h"
 
 #ifdef HAVE_CRYPTSETUP
diff --git a/libmount/src/hooks.c b/libmount/src/hooks.c
index 4340ac61ca..d0117e4562 100644
--- a/libmount/src/hooks.c
+++ b/libmount/src/hooks.c
@@ -10,14 +10,22 @@
  * (at your option) any later version.
  *
  *
- * The "hookset" is set of callbacks (hooks) that implement some functionality.
- * It supports two kinds of data:
+ * The "hookset" is a set of callbacks (hooks) that implement some functionality.
+ * The library defines stages where hooks are called (e.g. when preparing source, post
+ * mount(2), etc.). An arbitrary hook can, on the fly, define another hook for the
+ * arbitrary stage. The first hook from the hookset which goes to the game is a
+ * "firstcall" (defined in struct libmnt_hookset). This first hook controls
+ * what will happen in the next stages (usually nothing).
  *
- *  - global data    : accessible for all callbacks, independent on defined hooks
+ * The library supports two kinds of data for hooksets:
  *
- *  - per-hook data  : usually used by the callback function
+ * - global data;  accessible for all callbacks. Makes sense for complex
+ *   hooksets with more callbacks in more stages. Usually implemented by
+ *   locally defined 'struct hookset_data' in hook_*.c.
+ *
+ * - per-hook data; acessible for specific callback
+ *   Usually implemented by locally defined 'struct hook_data' in hook_*.c.
  */
-
 #include "mountP.h"
 #include "mount-api-utils.h"
 
@@ -39,7 +47,7 @@ static const struct libmnt_hookset *hooksets[] =
 #endif
 };
 
-/* hooksets data */
+/* hooksets data (this is global list of hookset data) */
 struct hookset_data {
 	const struct libmnt_hookset *hookset;
 	void *data;