From 4d3422b93181188bcff06c2938c70748ed9a3a5e Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Fri, 24 Jul 2020 14:24:03 +0200
Subject: [PATCH] [libcalamares] dox for Permissions

- Expand the documentation, emphasize octal-vs-decimal
- east-const consistently in this file (most of Calamares is west-const)
- shuffle the is-valid bool to the end of the data members,
  so sorting by size.
---
 src/libcalamares/utils/Permissions.cpp |  6 +++---
 src/libcalamares/utils/Permissions.h   | 29 ++++++++++++++++++++------
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/src/libcalamares/utils/Permissions.cpp b/src/libcalamares/utils/Permissions.cpp
index d9d3226e6..3166d840a 100644
--- a/src/libcalamares/utils/Permissions.cpp
+++ b/src/libcalamares/utils/Permissions.cpp
@@ -14,20 +14,20 @@
 Permissions::Permissions()
     : m_username()
     , m_group()
-    , m_valid( false )
     , m_value( 0 )
+    , m_valid( false )
 {
 }
 
 
-Permissions::Permissions( QString p )
+Permissions::Permissions( QString const& p )
     : Permissions()
 {
     parsePermissions( p );
 }
 
 void
-Permissions::parsePermissions( const QString& p )
+Permissions::parsePermissions( QString const& p )
 {
 
     QStringList segments = p.split( ":" );
diff --git a/src/libcalamares/utils/Permissions.h b/src/libcalamares/utils/Permissions.h
index baa5da554..b6e2d3a44 100644
--- a/src/libcalamares/utils/Permissions.h
+++ b/src/libcalamares/utils/Permissions.h
@@ -25,27 +25,44 @@ public:
     /** @brief Constructor
      *
      * Splits the string @p at the colon (":") into separate elements for
-     * <user>, <group>, and <value> (permissions), where <value> is returned as
-     * an **octal** integer.
+     * <user>, <group>, and <value> (permissions), where <value> is interpreted
+     * as an **octal** integer. That is, "root:wheel:755" will give
+     * you an integer value of four-hundred-ninety-three (493),
+     * corresponding to the UNIX file permissions rwxr-xr-x,
+     * as one would expect from chmod and other command-line utilities.
      */
-    Permissions( QString p );
+    Permissions( QString const& p );
 
-    /** @brief Default constructor of an invalid Permissions. */
+    /// @brief Default constructor of an invalid Permissions.
     Permissions();
 
+    /// @brief Was the Permissions object constructed from valid data?
     bool isValid() const { return m_valid; }
+    /// @brief The user (first component, e.g. "root" in "root:wheel:755")
     QString username() const { return m_username; }
+    /// @brief The group (second component, e.g. "wheel" in "root:wheel:755")
     QString group() const { return m_group; }
+    /** @brief The value (file permission) as an integer.
+     *
+     * Bear in mind that input is in octal, but integers are just integers;
+     * naively printing them will get decimal results (e.g. 493 from the
+     * input of "root:wheel:755").
+     */
     int value() const { return m_value; }
-    QString octal() const { return QString::number( m_value, 8 ); }
+    /** @brief The value (file permission) as octal string
+     *
+     * This is suitable for passing to chmod-the-program, or for
+     * recreating the original Permissions string.
+     */
+    QString octal() const { return QString::number( value(), 8 ); }
 
 private:
     void parsePermissions( QString const& p );
 
     QString m_username;
     QString m_group;
-    bool m_valid;
     int m_value;
+    bool m_valid;
 };
 
 #endif  // LIBCALAMARES_PERMISSIONS_H