completed the QtMvvmQuick qml doc

Author: Skycoder42

doc/Doxyfile

@@ -252,6 +252,7 @@ ALIASES                = "accessors{1}=<table><tr><th colspan= 2>Accessors</th><
 						 "constantAc=<tr><td colspan= 2><b>CONSTANT</b></td></tr>" \
 						 "readonlyAc=<tr><td colspan= 2><b>READ ONLY</b></td></tr>" \
 						 "finalAc=<tr><td colspan= 2><b>FINAL</b></td></tr>" \
+						 "defaultAc=<tr><td colspan= 2><b>DEFAULT</b></td></tr>" \
 						 "default{1}=<b>Default:</b> \1 <br>" \
 						 "readAcFn{1}=READ accessor for \1" \
 						 "writeAcFn{1}=WRITE accessor for \1" \
@@ -905,6 +906,7 @@ EXCLUDE                = ../src/3rdparty \
 						 ../src/imports/mvvmquick/InputDialog.qml \
 						 ../src/imports/mvvmquick/ListSection.qml \
 						 ../src/imports/mvvmquick/OverviewListView.qml \
+						 ../src/imports/mvvmquick/SectionListView.qml \
 						 ../src/imports/mvvmquick/AndroidFileDialog.qml \
 						 ../src/imports/mvvmquick/AndroidFolderDialog.qml
 

doc/makedoc.sh

@@ -41,9 +41,20 @@ if [ "$DOXY_STYLE_EXTRA" ]; then
 fi
 
 for tagFile in $(find "$qtDocs" -name *.tags); do
-	if [ $(basename "$tagFile") != "qtmvvm.tags" ]; then
-		echo "TAGFILES += \"$tagFile=https://doc.qt.io/qt-5\"" >> $doxyRes
-	fi
+	case $(basename "$tagFile") in
+		qtjsonserializer.tags)
+			echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QtJsonSerializer\"" >> $doxyRes
+			;;
+		qtdatasync.tags)
+			echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QtDataSync\"" >> $doxyRes
+			;;
+		qtmvvm.tags|qtquickcontrols.tags)
+			# skipped
+			;;
+		*)
+			echo "TAGFILES += \"$tagFile=https://doc.qt.io/qt-5\"" >> $doxyRes
+			;;
+	esac
 done
 
 cd "$srcDir"

src/imports/mvvmcore/qqmlmvvmbinding.h

@@ -11,6 +11,7 @@ namespace de::skycoder42::QtMvvm::Core {
 
 /*! @brief A QML class to create a local mvvm multiway binding
  *
+ * @extends QtQml.QtObject
  * @since 1.0
  *
  * It is basically a wrapper around the QtMvvm::bind method. The parameters are set via the

src/imports/mvvmcore/qqmlmvvmmessage.h

@@ -14,6 +14,7 @@ namespace de::skycoder42::QtMvvm::Core {
 
 /*! @brief A QML signelton to access the QtMvvm namespace methods for showing simple dialogs
  *
+ * @extends QtQml.QtObject
  * @since 1.0
  *
  * @sa QtMvvm::MessageConfig, QtMvvm::CoreApp::showDialog

src/imports/mvvmquick/ActionButton.qml

@@ -2,9 +2,27 @@ import QtQuick 2.10
 import QtQuick.Controls 2.3
 import de.skycoder42.QtMvvm.Quick 1.0
 
+/*! @brief An extension of the @ref QtQuick.Controls.ToolButton "ToolButton" for better appearance
+ *
+ * @extends QtQuick.Controls.ToolButton
+ *
+ * @details This version basically adjusts size, icon size and text display to look better and
+ * fit the Material guidelines. It also adds a tooltip that can be shown via a long press
+ *
+ * @sa ContrastToolBar, MenuButton
+ */
 ToolButton {
 	id: _toolButton
 
+	/*! @brief A toolTip to be shown when the button is long pressed
+	 *
+	 * @default{`ToolButton.text` (binding)}
+	 *
+	 * @accessors{
+	 *	@memberAc{toolTip}
+	 *  @notifyAc{toolTipChanged()}
+	 * }
+	 */
 	property string toolTip: _toolButton.text
 
 	display: AbstractButton.IconOnly

src/imports/mvvmquick/AlertDialog.qml

@@ -2,10 +2,44 @@ import QtQuick 2.10
 import QtQuick.Controls 2.3
 import QtQuick.Window 2.2
 
+/*! @brief An extension of the @ref QtQuick.Controls.Dialog "Dialog" for better appearance
+ *
+ * @extends QtQuick.Controls.Dialog
+ *
+ * @details This version basically adjusts size and makes shure the dialog always appears in
+ * center of the application. It even takes a possible input method into accout
+ */
 Dialog {
 	id: _alertDialog
 
+	/*! @brief Additional hight to give to the dialog
+	 *
+	 * @default{`0`}
+	 *
+	 * The dialog basically assumes that the parent is it's normal height plus this value. The
+	 * combined height is then used to calculate where to show the dialog. Can be used if the
+	 * parent does not fill up the whole application.
+	 *
+	 * @accessors{
+	 *	@memberAc{extraHeight}
+	 *  @notifyAc{extraHeightChanged()}
+	 * }
+	 */
 	property real extraHeight: 0
+	/*! @brief The ideal basic width of the dialog
+	 *
+	 * @default{`300`}
+	 *
+	 * Typically, the dialogs width is deduces by using the implicitWidth of it's contents and
+	 * is limited to the parents width. Howver some contents have no useful implicit width.
+	 * With this property, the dialog will try to be at least `baseWidth` or the contents
+	 * implicitWidth wide, whichever is bigger.
+	 *
+	 * @accessors{
+	 *	@memberAc{baseWidth}
+	 *  @notifyAc{baseWidthChanged()}
+	 * }
+	 */
 	property real baseWidth: 300
 
 	x: parent ? (parent.width - width) / 2 : 0
@@ -15,6 +49,16 @@ Dialog {
 	modal: true
 	focus: true
 
+	/*! @brief A function that calculates the value for the y coordiante
+	 *
+	 * @return type:real A value to be used as the `y` property value
+	 *
+	 * The value is calculated by taking the parent heigth, the dialog height, the input method
+	 * height and the extraHeight into account. I is calculated to center the dialog in the
+	 * parent.
+	 *
+	 * @sa Dialog::extraHeight
+	 */
 	function deltaY() {
 		var unscaled = Qt.inputMethod.keyboardRectangle.height / Screen.devicePixelRatio;
 		var availHeight = (parent.height + extraHeight) - unscaled - 24; //margins

src/imports/mvvmquick/ContrastToolBar.qml

@@ -2,11 +2,32 @@ import QtQuick 2.10
 import QtQuick.Controls 2.3
 import QtQuick.Controls.Material 2.3
 
+/*! @brief An extension of the @ref QtQuick.Controls.ToolBar "ToolBar" for better appearance
+ *
+ * @extends QtQuick.Controls.ToolBar
+ *
+ * @details This version basically adjusts size and text color of the toolbar itself and
+ * controls within the toolbar to look better and improve contrast
+ *
+ * @sa ActionButton, ToolBarLabel, MenuButton
+ */
 ToolBar {
 	id: _contrastToolBar
 
 	height: 56
 
+	/*! @brief Calculates the optimal text color based on the background color
+	 *
+	 * @param type:color accentColor The color to find a contrasting text color for
+	 * @param type:color baseColor The current default text color
+	 * @return type:color A color for text that is easy to read when used with accentColor as
+	 * the background
+	 *
+	 * The method calculates whether the color should be light or dark and then either returns
+	 * white or black, depending on which color fits better. If baseColor is specified, then
+	 * the color value is checked, too. If baseColor is easily readable, it is simply returned
+	 * as result. Otherwise the method proceeds as usual.
+	 */
 	function accentTextColor(accentColor, baseColor) {
 		var a = (0.299 * accentColor.r + 0.587 * accentColor.g + 0.144 * accentColor.b);
 		if(typeof baseColor !== "undefined") {

src/imports/mvvmquick/DialogPresenter.qml

@@ -3,11 +3,69 @@ import QtQuick.Controls 2.3
 import de.skycoder42.QtMvvm.Core 1.0
 import de.skycoder42.QtMvvm.Quick 1.0
 
+/*! @brief A presentation helper that can present generic mvvm dialogs
+ *
+ * @extends QtQml.QtObject
+ *
+ * @details You can use this class as presenter for dialogs in case you create your own root
+ * presenter instead of using the QtMvvmApp. This partial presenter can handle simple dialogs
+ * (the ones shown via QtMvvm::CoreApp::showDialog). Use it as follows:
+ *
+ * @code{.qml}
+ * MyPresenter {
+ *		id: _root
+ *
+ *		DialogPresenter {
+ *			id: _rootDialogs
+ *			rootItem: _root.contentItem
+ *		}
+ *
+ *		function showDialog(config, result) {
+ *			return _rootDialogs.showDialog(config, result);
+ *		}
+ *
+ *		function closeAction() {
+ *			var closed = false;
+ *			// ...
+ *			if(!closed)
+ *				closed = _rootDialogs.closeAction();
+ *			// ...
+ *			return closed;
+ *		}
+ * }
+ * @endcode
+ *
+ * @sa QtMvvmApp
+ */
 QtObject {
 	id: _dialogPresenter
 
+	/*! @brief The root item to present dialogs to
+	 *
+	 * @default{`null`}
+	 *
+	 * This propety **must** be set in order for the presenter to work. It will create new
+	 * dialogs with that item as parent, which decides in which relative are they are
+	 * displayed. Unless you want to explicitly reposition dialogs, this should always be the
+	 * root item of the root component of your application.
+	 *
+	 * @accessors{
+	 *	@memberAc{rootItem}
+	 *  @notifyAc{rootItemChanged()}
+	 * }
+	 */
 	property Item rootItem: null
 
+	/*! @brief The primary presenting method to present a dialog
+	 *
+	 * @param type:MessageConfig config The message configuration to create a dialog of
+	 * @param type:MessageResult result The result to report the dialog result to
+	 * @return type:bool `true` if successfully presented, `false` if not
+	 *
+	 * Use this method in your main presenter to present dialogs via this sub presenter.
+	 *
+	 * @sa QtMvvm::MessageConfig, QtMvvm::MessageResult, QtMvvmApp::showDialog
+	 */
 	function showDialog(config, result) {
 		if(config.type == "msgbox")
 			return createMsgBox(config, result)
@@ -19,6 +77,15 @@ QtObject {
 			return false;
 	}
 
+	/*! @brief Can be called to try to close open dialogs
+	 *
+	 * @return type:bool `true` if a dialog was closed, `false` if not
+	 *
+	 * Use this method in your main presenter react on a close event. It will close the
+	 * latest top level dialog, if one is present.
+	 *
+	 * @sa QtMvvmApp::closeAction
+	 */
 	function closeAction() {
 		if(_popups.length > 0) {
 			_popups[_popups.length - 1].reject();
@@ -27,7 +94,9 @@ QtObject {
 			return false;
 	}
 
+	//! Internal property
 	property var _popups: []
+	//! Internal property
 	property Component _msgBoxComponent: MsgBox {
 		id: __msgBox
 
@@ -45,6 +114,7 @@ QtObject {
 		}
 	}
 
+	//! Internal property
 	property Component _inputComponent: InputDialog {
 		id: __input
 
@@ -62,6 +132,7 @@ QtObject {
 		}
 	}
 
+	//! Internal property
 	property Component _fileComponent: FileDialog {
 		id: __file
 
@@ -79,6 +150,7 @@ QtObject {
 		}
 	}
 
+	//! Internal property
 	property Component _folderComponent: FolderDialog {
 		id: __folder
 
@@ -96,6 +168,18 @@ QtObject {
 		}
 	}
 
+	/*! @brief Method present a dialog of the QtMvvm::MessageConfig::TypeMessageBox
+	 *
+	 * @param type:MessageConfig config The message configuration to create a dialog of
+	 * @param type:MessageResult result The result to report the dialog result to
+	 * @return type:bool `true` if successfully presented, `false` if not
+	 *
+	 * Used by the showDialog() method to show a dialog of the message box type. You can use
+	 * it yourself if you want to extend the presenter and still keep the default dialogs it
+	 * supports.
+	 *
+	 * @sa DialogPresenter::showDialog
+	 */
 	function createMsgBox(config, result) {
 		var props = config.viewProperties;
 		props["msgConfig"] = config;
@@ -104,6 +188,18 @@ QtObject {
 		return incubator.status !== Component.Error;
 	}
 
+	/*! @brief Method present a dialog of the QtMvvm::MessageConfig::TypeInputDialog
+	 *
+	 * @param type:MessageConfig config The message configuration to create a dialog of
+	 * @param type:MessageResult result The result to report the dialog result to
+	 * @return type:bool `true` if successfully presented, `false` if not
+	 *
+	 * Used by the showDialog() method to show a dialog of the input dialog type. You can use
+	 * it yourself if you want to extend the presenter and still keep the default dialogs it
+	 * supports.
+	 *
+	 * @sa DialogPresenter::showDialog
+	 */
 	function createInput(config, result) {
 		var props = config.viewProperties;
 		props["msgConfig"] = config;
@@ -112,6 +208,18 @@ QtObject {
 		return incubator.status !== Component.Error;
 	}
 
+	/*! @brief Method present a dialog of the QtMvvm::MessageConfig::TypeFileDialog
+	 *
+	 * @param type:MessageConfig config The message configuration to create a dialog of
+	 * @param type:MessageResult result The result to report the dialog result to
+	 * @return type:bool `true` if successfully presented, `false` if not
+	 *
+	 * Used by the showDialog() method to show a dialog of the file dialog type. You can use
+	 * it yourself if you want to extend the presenter and still keep the default dialogs it
+	 * supports.
+	 *
+	 * @sa DialogPresenter::showDialog
+	 */
 	function createFile(config, result) {
 		var props = config.viewProperties;
 		props["msgConfig"] = config;