[buildd-tools-devel] [PATCH 10/11] [doc] Fix some doxygen class headers

[Jan-Marek Glogowski]

---
 sbuild/sbuild-chroot-block-device-base.h |   12 +++++++++---
 sbuild/sbuild-chroot-directory-base.h    |   14 +++++++++++++-
 sbuild/sbuild-chroot-directory.h         |    3 +++
 sbuild/sbuild-chroot-facet-mountable.h   |    9 ++++++++-
 sbuild/sbuild-chroot-facet-session.h     |    5 ++++-
 sbuild/sbuild-chroot-facet-source.h      |   10 +++++++++-
 sbuild/sbuild-chroot-facet-union.h       |   12 ++++++------
 sbuild/sbuild-chroot-file.h              |    5 +++--
 sbuild/sbuild-chroot-plain.h             |    6 +++++-
 9 files changed, 60 insertions(+), 16 deletions(-)

diff --git a/sbuild/sbuild-chroot-block-device-base.h b/sbuild/sbuild-chroot-block-device-base.h
index cbd9673..2bf8d44 100644
--- a/sbuild/sbuild-chroot-block-device-base.h
+++ b/sbuild/sbuild-chroot-block-device-base.h
@@ -23,11 +23,17 @@
 
 namespace sbuild
 {
-
   /**
-   * A chroot stored on an unmounted block device.
+   * A base class for block-device chroots.
    *
-   * The device will be mounted on demand.
+   * This class doesn't implement a chroot (get_chroot_type
+   * is not implemented).
+   * 
+   * Originally lvm-snapshot inherited from the block-device 
+   * chroot, but this was changed when union support was 
+   * introduced.  This design prevents lvm-snapshot to offer 
+   * union based sessions and forces the users to decide, if
+   * they want union or lvm-snapshot based session support.
    */
   class chroot_block_device_base : public chroot
   {
diff --git a/sbuild/sbuild-chroot-directory-base.h b/sbuild/sbuild-chroot-directory-base.h
index d2adf93..ae49e75 100644
--- a/sbuild/sbuild-chroot-directory-base.h
+++ b/sbuild/sbuild-chroot-directory-base.h
@@ -25,7 +25,19 @@ namespace sbuild
 {
 
   /**
-   * A chroot located in the filesystem (mounts disabled).
+   * A base class for chroots located in a local directory.
+   *
+   * This class doesn't implement a chroot (get_chroot_type
+   * is not implemented).
+   *
+   * Originally plain inherited from the directory chroot, but
+   * this had to be changed when union support was introduced.
+   * As plain chroots don't run any setup scripts and basically
+   * just call 'chroot' on a directory, they can't support 
+   * union based sessions.
+   *
+   * Therefore plain and directory chroots inherit from this
+   * class.
    */
   class chroot_directory_base : public chroot
   {
diff --git a/sbuild/sbuild-chroot-directory.h b/sbuild/sbuild-chroot-directory.h
index a8dd3ba..ea04d80 100644
--- a/sbuild/sbuild-chroot-directory.h
+++ b/sbuild/sbuild-chroot-directory.h
@@ -27,6 +27,9 @@ namespace sbuild
 
   /**
    * A chroot located in the filesystem.
+   *
+   * It runs setup scripts and can provide multiple sessions
+   * using the union facet.
    */
   class chroot_directory : public chroot_directory_base
   {
diff --git a/sbuild/sbuild-chroot-facet-mountable.h b/sbuild/sbuild-chroot-facet-mountable.h
index 7ab0bb5..eb8a19c 100644
--- a/sbuild/sbuild-chroot-facet-mountable.h
+++ b/sbuild/sbuild-chroot-facet-mountable.h
@@ -25,7 +25,14 @@ namespace sbuild
 {
 
   /**
-   * Chroot support for kernel personalities (execution domains).
+   * Chroot support for mountable devices and filesystems.
+   *
+   * This facet should be selected for sessions using the mount
+   * command to create the chroot.  The specified device will be
+   * mounted on demand.
+   *
+   * This facet is not restricted to block devices and can also be
+   * used for network filesystems.
    */
   class chroot_facet_mountable : public chroot_facet
   {
diff --git a/sbuild/sbuild-chroot-facet-session.h b/sbuild/sbuild-chroot-facet-session.h
index 74d2ab4..cbc9de6 100644
--- a/sbuild/sbuild-chroot-facet-session.h
+++ b/sbuild/sbuild-chroot-facet-session.h
@@ -26,7 +26,10 @@ namespace sbuild
 {
 
   /**
-   * Chroot support for kernel personalities (execution domains).
+   * Chroot support for sessions.
+   *
+   * A chroot may offer a "session" facet to signal restorable
+   * or parallel chroot environment usage.
    */
   class chroot_facet_session : public chroot_facet
   {
diff --git a/sbuild/sbuild-chroot-facet-source.h b/sbuild/sbuild-chroot-facet-source.h
index 1fe0867..4ce453f 100644
--- a/sbuild/sbuild-chroot-facet-source.h
+++ b/sbuild/sbuild-chroot-facet-source.h
@@ -25,7 +25,15 @@ namespace sbuild
 {
 
   /**
-   * Chroot support for kernel personalities (execution domains).
+   * Chroot support for clonable sources.
+   *
+   * A chroot may offer a "source" facet in addition to its normal
+   * "session" copy, to allow for maintenence of the source data.
+   * This facet can be used by any chroot wishing to provide such 
+   * functionality.
+   *
+   * A chroot providing this facet is always clonable.  Therefore
+   * clone_source_setup removes the facet from the cloned chroot.
    */
   class chroot_facet_source : public chroot_facet
   {
diff --git a/sbuild/sbuild-chroot-facet-union.h b/sbuild/sbuild-chroot-facet-union.h
index 442f183..560e673 100644
--- a/sbuild/sbuild-chroot-facet-union.h
+++ b/sbuild/sbuild-chroot-facet-union.h
@@ -26,13 +26,13 @@ namespace sbuild
 {
 
   /**
-   * A chroot may offer session support using a filesystem union like
-   * aufs or unionfs.  This is an extension interface class, not a
-   * chroot type in its own right.
+   * Chroot support for filesystem union based sessions.
    *
-   * At a minimum, the inheriting class has to implement the
-   * chroot::clone_source() function, depending upon the setting of
-   * get_union_configured().
+   * A chroot may offer session support using a filesystem union like
+   * aufs or unionfs.  A new chroot may need to adapt the 10mount or
+   * 05union script to properly populate the underlay and mount
+   * directory.  The overlay directory and union setup is already
+   * handled.
    */
   class chroot_facet_union : public chroot_facet
   {
diff --git a/sbuild/sbuild-chroot-file.h b/sbuild/sbuild-chroot-file.h
index d25447d..0d30477 100644
--- a/sbuild/sbuild-chroot-file.h
+++ b/sbuild/sbuild-chroot-file.h
@@ -25,8 +25,9 @@ namespace sbuild
 {
 
   /**
-   * A chroot stored in a file archive (tar or zip).  The archive will
-   * be unpacked on demand.
+   * A chroot stored in a file archive (tar or zip).
+   *
+   * The archive will be unpacked and repacked on demand.
    */
   class chroot_file : public chroot
   {
diff --git a/sbuild/sbuild-chroot-plain.h b/sbuild/sbuild-chroot-plain.h
index 937e6a5..d51f3fe 100644
--- a/sbuild/sbuild-chroot-plain.h
+++ b/sbuild/sbuild-chroot-plain.h
@@ -25,7 +25,11 @@ namespace sbuild
 {
 
   /**
-   * A chroot located in the filesystem (mounts disabled).
+   * A chroot located in the filesystem (scripts disabled).
+   *
+   * This doesn't run any setup scripts and doesn't provide any
+   * session support. If you need any of these take a look at 
+   * the directory chroot type.
    */
   class chroot_plain : public chroot_directory_base
   {
-- 
1.6.4