updated settings doc, try prebuilt image

Author: Skycoder42

.travis.yml

@@ -20,6 +20,7 @@ matrix:
         - PLATFORM=gcc_64
         - BUILD_DOC=true
         - BUILD_EXAMPLES=true
+        - DOCKER_IMAGE=datasync
     - os: linux
       env:
         - PLATFORM=android_armv7

doc/settingssetup.dox

@@ -0,0 +1,49 @@
+/*!
+@class QtMvvm::ISettingsSetupLoader
+
+It is used by the SettingsViewModel to load a SettingsElements::Setup from a generic file. The
+default implementation that is used by default implements a loader for an XML format. You can
+implement your own format, but unless you need to open things other then normal files/resources
+(or hate XML), there is no advantage of doing so.
+
+@sa #QtMvvm_ISettingsSetupLoaderIid, SettingsViewModel, SettingsLoaderException,
+SettingsElements::Setup, TODO link to xml doc
+*/
+
+/*!
+@fn QtMvvm::ISettingsSetupLoader::changeDefaultIcon
+
+@param defaultIcon The URL to the icon to use as overwrite
+
+The default icon used by the XML loader is `qrc:/de/skycoder42/qtmvvm/icons/settings.svg`. If
+you want to overwrite that path (for example because you want to use a png instead of a svg
+icon) you can do so via this function
+
+@sa SettingsDialog::iconOverwrite
+*/
+
+/*!
+@fn QtMvvm::ISettingsSetupLoader::loadSetup
+
+@param filePath The path to the file to be loaded
+@param frontend The name of the GUI frontend beeing used
+@param selector The currently active file selectors
+@returns The loaded and filtered settings setup
+@throws SettingsLoaderException In case the loaded file is invalid
+
+The frontend is used to filter elements by their `frontends` variable. It is always the name of
+the view type that is loading the settings via the viewmodel. Current values are:
+
+- `widgets` for the Widgets GUI
+- `quick` for the Quick Controls 2 GUI
+
+The selector should be used to a.) select the files to open (event the one passed). Use the
+select method to apply the paths. This applies for the elements as well, via the `selectors`
+variable.
+
+@note The syntax etc of these two variables depends on your loader and they are only used by you,
+not by anyone using this method. The default syntax used by the XML load implementation can be
+found in the TODO xml doc
+
+@sa SettingsElements::Setup, QFileSelector, TODO xml doc
+*/

src/mvvmcore/settingssetup.h

@@ -15,73 +15,111 @@ namespace QtMvvm {
 //! A sub namespace for the different elements in a settings setup
 namespace SettingsElements {
 
+//! An entry in the settings to display and edit a value
 struct Entry
 {
+	//! The QSettings key this entry should handle
 	QString key;
+	//! The input view type (typically the actual data type) to show
 	QByteArray type;
+	//! A short title/label of the entry to give it a name
 	QString title;
+	//! A tooltip with more detailed information about the entry
 	QString tooltip;
+	//! A default value to display in case no value is in the settings yet
 	QVariant defaultValue;
+	//! A list of keys to find this entry by when searching
 	QStringList searchKeys;
+	//! Additional properties to be passed on to the edit view
 	QVariantMap properties;
 
+	//! *[Internal]* A logical string describing the allowed frontends
 	QString frontends;
+	//! *[Internal]* A logical string describing the allowed selectors
 	QString selectors;
 };
 
+//! A logical group of settings entries
 struct Group
 {
+	//! The groups title
 	QString title;
+	//! A tooltip to describe what the group is about
 	QString tooltip;
 
+	//! A list of entries the group contains
 	QList<Entry> entries;
 
+	//! *[Internal]* A logical string describing the allowed frontends
 	QString frontends;
+	//! *[Internal]* A logical string describing the allowed selectors
 	QString selectors;
 };
 
+//! A bigger section for different entries and groups
 struct Section
 {
+	//! The sections title
 	QString title;
+	//! An icon for the section
 	QUrl icon;
+	//! A tooltip to describe what the section is about
 	QString tooltip;
 
+	//! A list of groups the section contains
 	QList<Group> groups;
 
+	//! *[Internal]* A logical string describing the allowed frontends
 	QString frontends;
+	//! *[Internal]* A logical string describing the allowed selectors
 	QString selectors;
 };
 
+//! A top level category to organize sections in
 struct Category
 {
+	//! The categories title
 	QString title;
+	//! An icon for the category
 	QUrl icon;
+	//! A tooltip to describe what the category is about
 	QString tooltip;
 
+	//! A list of sections the category contains
 	QList<Section> sections;
 
+	//! *[Internal]* A logical string describing the allowed frontends
 	QString frontends;
+	//! *[Internal]* A logical string describing the allowed selectors
 	QString selectors;
 };
 
+//! The whole settings setup
 struct Setup
 {
+	//! Specifies if the user is allowed to search in the settings
 	bool allowSearch = true;
+	//! Specifies if the user is allowed to restore the factory defaults
 	bool allowRestore = true;
 
+	//! A list of categories the setup is build of
 	QList<Category> categories;
 };
 
 }
 
+//! An exception throw in case loading a settings setup went wrong
 class SettingsLoaderException : public QException {};
 
+//! An interface for a generic settings setup loader
 class ISettingsSetupLoader
 {
 public:
 	virtual inline ~ISettingsSetupLoader() = default;
 
+	//! Can be used to overwrite the default icon for categories
 	virtual void changeDefaultIcon(const QUrl &defaultIcon) = 0;
+	//! Loads the settings setup from the given file
 	virtual SettingsElements::Setup loadSetup(const QString &filePath, const QString &frontend, const QFileSelector *selector) const = 0;
 };
 
@@ -93,8 +131,10 @@ Q_DECLARE_METATYPE(QtMvvm::SettingsElements::Section)
 Q_DECLARE_METATYPE(QtMvvm::SettingsElements::Category)
 Q_DECLARE_METATYPE(QtMvvm::SettingsElements::Setup)
 
+//! The Iid of the QtMvvm::ISettingsSetupLoader class
 #define QtMvvm_ISettingsSetupLoaderIid "de.skycoder42.qtmvvm.settings.core.ISettingsSetupLoader"
 Q_DECLARE_INTERFACE(QtMvvm::ISettingsSetupLoader, QtMvvm_ISettingsSetupLoaderIid)
 Q_DECLARE_METATYPE(QtMvvm::ISettingsSetupLoader*)
 
+//! @file settingssetup.h The settings setup header
 #endif // QTMVVM_SETTINGSSETUP_H