Documentation++

src/libcalamares/utils/CalamaresUtils.h

@@ -33,15 +33,41 @@
 class QDir;
 class QObject;
 
+/**
+ * @brief The CalamaresUtils namespace contains utility functions.
+ */
 namespace CalamaresUtils
 {
     DLLEXPORT QDir qmlModulesDir();
+
+    /**
+     * @brief appDataDir returns the directory with common application data.
+     * Defaults to CMAKE_INSTALL_FULL_DATADIR (usually /usr/share/calamares).
+     */
     DLLEXPORT QDir appDataDir();
+
+    /**
+     * @brief appLogDir returns the directory for Calamares logs.
+     * Defaults to QStandardPaths::CacheLocation (usually ~/.cache/Calamares).
+     */
     DLLEXPORT QDir appLogDir();
+
+    /**
+     * @brief systemLibDir returns the system's lib directory.
+     * Defaults to CMAKE_INSTALL_FULL_LIBDIR (usually /usr/lib64 or /usr/lib).
+     */
     DLLEXPORT QDir systemLibDir();
+
+    /**
+     * @brief installTranslator changes the application language.
+     * @param locale the new locale.
+     * @param brandingTranslationsPrefix the branding path prefix, from Calamares::Branding.
+     * @param parent the parent QObject.
+     */
     DLLEXPORT void installTranslator( const QLocale& locale,
                                       const QString& brandingTranslationsPrefix,
                                       QObject* parent );
+
     DLLEXPORT QString translatorLocaleName();
 
     /**
@@ -52,10 +78,24 @@ namespace CalamaresUtils
 
     DLLEXPORT void setQmlModulesDir( const QDir& dir );
 
+    /**
+     * @brief removeDiacritics replaces letters with diacritics and ligatures with
+     * alternative forms and digraphs.
+     * @param string the string to transform.
+     * @return the output string with plain characters.
+     */
     DLLEXPORT QString removeDiacritics( const QString& string );
 
+    /**
+     * @brief obscure is a bidirectional obfuscation function, from KStringHandler.
+     * @param string the input string.
+     * @return the obfuscated string.
+     */
     DLLEXPORT QString obscure( const QString& string );
 
+    /**
+     * @brief crash makes Calamares crash immediately.
+     */
     DLLEXPORT void crash();
 }
 

src/libcalamares/utils/CalamaresUtilsSystem.h

@@ -26,10 +26,20 @@
 namespace CalamaresUtils
 {
 
+/**
+ * @brief The System class is a singleton with utility functions that perform
+ * system-specific operations.
+ */
 class DLLEXPORT System : public QObject
 {
     Q_OBJECT
 public:
+    /**
+     * @brief System the constructor. Only call this once in a Calamares instance.
+     * @param doChroot set to true if all external commands should run in the
+     * target system chroot, otherwise false to run everything on the current system.
+     * @param parent the QObject parent.
+     */
     explicit System( bool doChroot, QObject* parent = nullptr );
     virtual ~System();
 
@@ -37,6 +47,10 @@ public:
 
     /**
       * Runs the mount utility with the specified parameters.
+      * @param devicePath the path of the partition to mount.
+      * @param mountPoint the full path of the target mount point.
+      * @param filesystemName the name of the filesystem (optional).
+      * @param options any additional options as passed to mount -o (optional).
       * @returns the program's exit code, or:
       *             -1 = QProcess crash
       *             -2 = QProcess cannot start
@@ -49,6 +63,13 @@ public:
 
     /**
       * Runs the specified command in the chroot of the target system.
+      * @param args the call with arguments, as a string list.
+      * @param workingPath the current working directory for the QProcess
+      * call (optional).
+      * @param stdInput the input string to send to the running process as
+      * standard input (optional).
+      * @param timeoutSec the timeout after which the process will be
+      * killed (optional, default is 0 i.e. no timeout).
       * @returns the program's exit code, or:
       *             -1 = QProcess crash
       *             -2 = QProcess cannot start
@@ -77,9 +98,11 @@ public:
                                 const QString& stdInput = QString(),
                                 int timeoutSec = 0 );
 
-    DLLEXPORT qint64 getPhysicalMemoryB();  //Better guess, doesn't work in VirualBox
+    /**
-
+     * @brief getTotalMemoryB returns the total main memory, in bytes.
+     */
     DLLEXPORT qint64 getTotalMemoryB();     //Always underguessed, but always works on Linux
+    DLLEXPORT qint64 getPhysicalMemoryB();  //Better guess, doesn't work in VirualBox
 
 private:
     static System* s_instance;

src/libcalamaresui/utils/CalamaresUtilsGui.h

@@ -29,6 +29,14 @@ class QLayout;
 
 namespace CalamaresUtils
 {
+
+/**
+ * @brief The ImageType enum lists all common Calamares icons.
+ * Icons are loaded from SVGs and cached. Each icon has an enum value, through which
+ * it can be accessed.
+ * You can forward-declare this as:
+ * enum ImageType : int;
+ */
 enum ImageType : int
 {
     Yes,
@@ -49,6 +57,10 @@ enum ImageType : int
     Squid
 };
 
+/**
+ * @brief The ImageMode enum contains different transformations that can be applied.
+ * Most of these are currently unused.
+ */
 enum ImageMode
 {
     Original,
@@ -58,15 +70,46 @@ enum ImageMode
     RoundedCorners
 };
 
-UIDLLEXPORT QPixmap defaultPixmap( ImageType type, ImageMode mode = CalamaresUtils::Original, const QSize& size = QSize( 0, 0 ) );
+/**
-UIDLLEXPORT QPixmap createRoundedImage( const QPixmap& avatar, const QSize& size, float frameWidthPct = 0.20 );
+ * @brief defaultPixmap returns a resized and/or transformed pixmap for a given
+ * ImageType.
+ * @param type the ImageType i.e. the enum value for an SVG.
+ * @param mode the transformation to apply (default: no transformation).
+ * @param size the target pixmap size (default: original SVG size).
+ * @return the new pixmap.
+ */
+UIDLLEXPORT QPixmap defaultPixmap( ImageType type,
+                                   ImageMode mode = CalamaresUtils::Original,
+                                   const QSize& size = QSize( 0, 0 ) );
 
+/**
+ * @brief createRoundedImage returns a rounded version of a pixmap.
+ * @param avatar the input pixmap.
+ * @param size the new size.
+ * @param frameWidthPct the frame size, as percentage of width.
+ * @return the transformed pixmap.
+ * This one is currently unused.
+ */
+UIDLLEXPORT QPixmap createRoundedImage( const QPixmap& avatar,
+                                        const QSize& size,
+                                        float frameWidthPct = 0.20 );
+
+/**
+ * @brief unmarginLayout recursively walks the QLayout tree and removes all margins.
+ * @param layout the layout to unmargin.
+ */
 UIDLLEXPORT void unmarginLayout( QLayout* layout );
+
+/**
+ * @brief clearLayout recursively walks the QLayout tree and deletes all the child
+ * widgets and layouts.
+ * @param layout the layout to clear.
+ */
 UIDLLEXPORT void clearLayout( QLayout* layout );
 
 UIDLLEXPORT void setDefaultFontSize( int points );
-UIDLLEXPORT int defaultFontSize();
+UIDLLEXPORT int defaultFontSize();      // in points
-UIDLLEXPORT int defaultFontHeight();
+UIDLLEXPORT int defaultFontHeight();    // in pixels, DPI-specific
 UIDLLEXPORT QFont defaultFont();
 UIDLLEXPORT QSize defaultIconSize();
 

src/libcalamaresui/viewpages/PythonQtUtilsWrapper.h

@@ -24,6 +24,10 @@
 #include <QObject>
 
 
+/**
+ * @brief The Utils class wraps around functions from CalamaresUtils to make them
+ * available in the PythonQt interface.
+ */
 class Utils : public QObject
 {
     Q_OBJECT

src/modules/partition/core/ColorUtils.h

@@ -34,6 +34,12 @@ QColor freeSpaceColor();
 
 QColor unknownDisklabelColor();
 
+/**
+ * @brief colorForPartition iterates over partitions, caches their colors and returns
+ * a color for the given partition.
+ * @param partition the partition for which to return a color.
+ * @return a color for the partition.
+ */
 QColor colorForPartition( Partition* partition );
 
 /**
@@ -42,6 +48,9 @@ QColor colorForPartition( Partition* partition );
  */
 QColor colorForPartitionInFreeSpace( Partition* freeSpacePartition );
 
+/**
+ * @brief invalidateCache clears the partition colors cache.
+ */
 void invalidateCache();
 
 }

src/modules/partition/core/PartUtils.h

@@ -29,12 +29,37 @@ class Partition;
 namespace PartUtils
 {
 
+/**
+ * @brief canBeReplaced checks whether the given Partition satisfies the criteria
+ * for replacing it with the new OS.
+ * @param candidate the candidate partition to replace.
+ * @return true if the criteria are met, otherwise false.
+ */
 bool canBeReplaced( Partition* candidate );
 
+/**
+ * @brief canBeReplaced checks whether the given Partition satisfies the criteria
+ * for resizing (shrinking) it to make room for a new OS.
+ * @param candidate the candidate partition to resize.
+ * @return true if the criteria are met, otherwise false.
+ */
 bool canBeResized( Partition* candidate );
 
+/**
+ * @brief canBeReplaced checks whether the given Partition satisfies the criteria
+ * for resizing (shrinking) it to make room for a new OS.
+ * @param core the PartitionCoreModule instance.
+ * @param partitionPath the device path of the candidate partition to resize.
+ * @return true if the criteria are met, otherwise false.
+ */
 bool canBeResized( PartitionCoreModule* core, const QString& partitionPath );
 
+/**
+ * @brief runOsprober executes os-prober, parses the output and writes relevant
+ * data to GlobalStorage.
+ * @param core the PartitionCoreModule instance.
+ * @return a list of os-prober entries, parsed.
+ */
 OsproberEntryList runOsprober( PartitionCoreModule* core );
 
 }