Merge pull request #3900 from DonLakeFlyer/Doygen

Doxygen qml support

doc/Doxyfile

@@ -216,7 +216,7 @@ OPTIMIZE_OUTPUT_VHDL   = NO
 # .inc files as Fortran files (default is PHP), and .f files as C (default is Fortran),
 # use: inc=Fortran f=C. Note that for custom extensions you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
 
-EXTENSION_MAPPING      =
+EXTENSION_MAPPING      = qml=C++
 
 # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
 # to include (a tag file for) the STL sources as input, then you should
@@ -668,7 +668,7 @@ INPUT_FILTER           =
 # info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER
 # is applied to all files.
 
-FILTER_PATTERNS        =
+FILTER_PATTERNS        = *.qml=/usr/local/bin/doxyqml
 
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
 # INPUT_FILTER) will be used to filter the input files when producing source

src/QGCMapPalette.h

@@ -8,38 +8,55 @@
  ****************************************************************************/
 
 
-/// QGCMapPalette is a variant of QGCPalette which is used to hold colors used for display over
-/// the map control. Since the coloring of a satellite map differs greatly from the coloring of
-/// a street map you need to be able to switch between sets of color based on map type.
-
 #ifndef QGCMapPalette_h
 #define QGCMapPalette_h
 
 #include <QObject>
 #include <QColor>
 
+/*!
+ QGCMapPalette is a variant of QGCPalette which is used to hold colors used for display over
+ the map control. Since the coloring of a satellite map differs greatly from the coloring of
+ a street map you need to be able to switch between sets of color based on map type.
+
+ Usage:
+
+        import QGroundControl.Palette 1.0
+
+        FlightMap {
+            id:             map
+            anchors.fill:   parent
+
+            QGCMapPalette { id: mapPal: lightColors: map.isSatelliteMap }
+
+            QGCLabel {
+                text:   "Text over map"
+                color:  mapPal.text
+            }
+        }
+**/
+
 class QGCMapPalette : public QObject
 {
     Q_OBJECT
     
     Q_PROPERTY(bool lightColors READ lightColors WRITE setLightColors NOTIFY paletteChanged)
 
-    // The colors are:
-    //      text            - Text color
-    //      thumbJoystick   - Thumb joystick indicator
-
     Q_PROPERTY(QColor text          READ text          NOTIFY paletteChanged)
     Q_PROPERTY(QColor thumbJoystick READ thumbJoystick NOTIFY paletteChanged)
 
 public:    
     QGCMapPalette(QObject* parent = NULL);
     
-    bool lightColors(void) const { return _lightColors; }
-    void setLightColors(bool lightColors);
-    
+    /// Text color
     QColor text(void)           const { return _text[_lightColors ? 0 : 1]; }
+
+    /// Thumb joystick indicator
     QColor thumbJoystick(void)  const { return _thumbJoystick[_lightColors ? 0 : 1]; }
 
+    bool lightColors(void) const { return _lightColors; }
+    void setLightColors(bool lightColors);    
+
 signals:
     void paletteChanged(void);
     void lightColorsChanged(bool lightColors);

src/QGCPalette.h

@@ -7,21 +7,29 @@
  *
  ****************************************************************************/
 
-
-/// @file
-///     @brief QGCPalette is used by QML ui to bind colors to the QGC pallete. The implementation
-///             is similar to the QML SystemPalette and should be used in the same way. Refer to
-///             that documentation for details. The one difference is that QGCPalette also supports
-///             a light and dark theme which you can switch between.
-///
-///     @author Don Gagne <don@thegagnes.com>
-
 #ifndef QGCPalette_h
 #define QGCPalette_h
 
 #include <QObject>
 #include <QColor>
 
+/*!
+ QGCPalette is used in QML ui to expose color properties for the QGC palette. There are two
+ separate palettes in QGC, light and dark. The light palette is for outdoor use and the dark
+ palette is for indoor use. Each palette also has a set of different colors for enabled and
+ disabled states.
+
+ Usage:
+
+        import QGroundControl.Palette 1.0
+
+        Rectangle {
+            anchors.fill:   parent
+            color:          qgcPal.window
+
+            QGCPalette { id: qgcPal: colorGroupEnabled: enabled }
+        }
+*/
 class QGCPalette : public QObject
 {
     Q_OBJECT
@@ -32,30 +40,6 @@ class QGCPalette : public QObject
     
     Q_PROPERTY(bool colorGroupEnabled READ colorGroupEnabled WRITE setColorGroupEnabled NOTIFY paletteChanged)
 
-    // The colors are:
-    //      window -                Background color for windows
-    //      windowShade -           Color for shaded areas within a window. The windowShade color should be a color somewhere between window and button.
-    //      windowShadeDark -       Color for darker shared areas within a window. The windowShadeDark color should be a color somewhere between window and windowShade.
-    //      text -                  Standard text color for label text
-    //      warningText -           Color for warning text
-    //      button -                Background color for buttons
-    //      buttonText -            Text color for buttons
-    //      buttonHighlight -       Background color for button in selected or hover state
-    //      buttonHighlightText -   Text color for button in selected or hover state
-
-    //      primaryButton -         Background color for primary buttons. A primary button is the button which would be the
-    //                              normal default  button to press. For example in an Ok/Cancel situation where Ok would normally
-    //                              be pressed, Ok is the primary button.
-    //      primaryButtonText -     Text color for primary buttons
-    //      textField -             Background color for TextFields
-    //      textFieldText -         Text color for TextFields
-    //      mapButton -             Background color for map buttons
-    //      mapButtonHighlight -    Background color for map button in selected or hover state
-    //      mapWidgetBorderLight -  Widget border color which will stand out against light map tiles
-    //      mapWidgetBorderDark -   Widget border color which will stand out against dark map tiles
-    //      brandingPurple -        Purple color from branding guidelines
-    //      brandingBlue -          Blue color from branding guidelines
-
     Q_PROPERTY(QColor window                READ window                 WRITE setWindow                 NOTIFY paletteChanged)
     Q_PROPERTY(QColor windowShade           READ windowShade            WRITE setWindowShade            NOTIFY paletteChanged)
     Q_PROPERTY(QColor windowShadeDark       READ windowShadeDark        WRITE setWindowShadeDark        NOTIFY paletteChanged)
@@ -93,24 +77,62 @@ public:
     bool colorGroupEnabled(void) const { return _colorGroupEnabled; }
     void setColorGroupEnabled(bool enabled);
     
+    /// Background color for windows
     QColor window(void)                 const { return _window[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Color for shaded areas within a window. The windowShade color is a color between window and button.
     QColor windowShade(void)            const { return _windowShade[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Color for darker shared areas within a window. The windowShadeDark color is a color between window and windowShade.
     QColor windowShadeDark(void)        const { return _windowShadeDark[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Text color
     QColor text(void)                   const { return _text[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Color for warning text
     QColor warningText(void)            const { return _warningText[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Background color for buttons
     QColor button(void)                 const { return _button[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Text color for buttons
     QColor buttonText(void)             const { return _buttonText[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Background color for button in selected or hover state
     QColor buttonHighlight(void)        const { return _buttonHighlight[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Text color for button in selected or hover state
     QColor buttonHighlightText(void)    const { return _buttonHighlightText[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Background color for primary buttons. A primary button is the button which would be the normal default  button to press.
+    /// For example in an Ok/Cancel situation where Ok would normally be pressed, Ok is the primary button.
     QColor primaryButton(void)          const { return _primaryButton[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Text color for primary buttons
     QColor primaryButtonText(void)      const { return _primaryButtonText[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Background color for TextFields
     QColor textField(void)              const { return _textField[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Text color for TextFields
     QColor textFieldText(void)          const { return _textFieldText[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Background color for map buttons
     QColor mapButton(void)              const { return _mapButton[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Background color for map button in selected or hover state
     QColor mapButtonHighlight(void)     const { return _mapButtonHighlight[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Widget border color which will stand out against light map tiles
     QColor mapWidgetBorderLight(void)   const { return _mapWidgetBorderLight[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Widget border color which will stand out against dark map tiles
     QColor mapWidgetBorderDark(void)    const { return _mapWidgetBorderDark[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Purple color from branding guidelines
     QColor brandingPurple(void)         const { return _brandingPurple[_theme][_colorGroupEnabled ? 1 : 0]; }
+
+    /// Blue color from branding guidelines
     QColor brandingBlue(void)           const { return _brandingBlue[_theme][_colorGroupEnabled ? 1 : 0]; }
 
     void setWindow(QColor& color)               { _window[_theme][_colorGroupEnabled ? 1 : 0] = color; _signalPaletteChangeToAll(); }

src/QmlControls/ScreenTools.qml

@@ -7,21 +7,47 @@ import QtQuick.Window 2.2
 import QGroundControl                       1.0
 import QGroundControl.ScreenToolsController 1.0
 
+/*!
+ The ScreenTools Singleton provides information on QGC's standard font metrics. It also provides information on screen
+ size which can be used to adjust user interface for varying available screen real estate.
+
+ QGC has four standard font sizes: default, small, medium and large. The QGC controls use the default font for display and you should use this font
+ for most text within the system that is drawn using something other than a standard QGC control. The small font is smaller than the default font.
+ The medium and large fonts are larger than the default font.
+
+ Usage:
+
+        import QGroundControl.ScreenTools 1.0
+
+        Rectangle {
+            anchors.fill:       parent
+            anchors.margins:    ScreenTools.defaultFontPixelWidth
+            ...
+        }
+*/
 Item {
     id: _screenTools
 
-    signal repaintRequested
-
-    property real availableHeight:          0
+    //-- The point and pixel font size values are computed at runtime
 
-    //-- These are computed at runtime
     property real defaultFontPointSize:     10
+
+    /// You can use this property to position ui elements in a screen resolution independant manner. Using fixed positioning values should not
+    /// be done. All positioning should be done using anchors or a ratio of the defaultFontPixelHeight and defaultFontPixelWidth values. This way
+    /// your ui elements will reposition themselves appropriately on varying screen sizes and resolutions.
     property real defaultFontPixelHeight:   10
+
+    /// You can use this property to position ui elements in a screen resolution independant manner. Using fixed positioning values should not
+    /// be done. All positioning should be done using anchors or a ratio of the defaultFontPixelHeight and defaultFontPixelWidth values. This way
+    /// your ui elements will reposition themselves appropriately on varying screen sizes and resolutions.
     property real defaultFontPixelWidth:    10
+
     property real smallFontPointSize:       10
     property real mediumFontPointSize:      10
     property real largeFontPointSize:       10
 
+    property real availableHeight:          0
+
     readonly property real smallFontPointRatio:      0.75
     readonly property real mediumFontPointRatio:     1.25
     readonly property real largeFontPointRatio:      1.5
@@ -43,19 +69,22 @@ Item {
         target: QGroundControl
         onBaseFontPointSizeChanged: {
             if(ScreenToolsController.isDebug)
-                setBasePointSize(QGroundControl.baseFontPointSize)
+                _setBasePointSize(QGroundControl.baseFontPointSize)
         }
     }
 
+    /// Returns the current x position of the mouse in global screen coordinates.
     function mouseX() {
         return ScreenToolsController.mouseX()
     }
 
+    /// Returns the current y position of the mouse in global screen coordinates.
     function mouseY() {
         return ScreenToolsController.mouseY()
     }
 
-    function setBasePointSize(pointSize) {
+    /// \private
+    function _setBasePointSize(pointSize) {
         _textMeasure.font.pointSize = pointSize
         defaultFontPointSize    = pointSize
         defaultFontPixelHeight  = _textMeasure.fontHeight
@@ -111,10 +140,10 @@ Item {
                 QGroundControl.baseFontPointSize = baseSize
                 //-- Release build doesn't get signal
                 if(!ScreenToolsController.isDebug)
-                    _screenTools.setBasePointSize(baseSize);
+                    _screenTools._setBasePointSize(baseSize);
             } else {
                 //-- Set size saved in settings
-                _screenTools.setBasePointSize(baseSize);
+                _screenTools._setBasePointSize(baseSize);
             }
         }
     }