#106 improve doxygen comments

dave · dave · commit 9210ad57f31b · 2021-05-24T13:43:01.000+01:00
diff --git a/examples/esp32Lcd/Esp32Lcd.emf b/examples/esp32Lcd/Esp32Lcd.emf
@@ -81,6 +81,88 @@
         "localOnly": false,
         "visible": true
       }
+    },
+    {
+      "parentId": 0,
+      "type": "subMenu",
+      "item": {
+        "secured": false,
+        "name": "Grid",
+        "variableName": "Grid",
+        "id": 6,
+        "eepromAddress": -1,
+        "readOnly": false,
+        "localOnly": false,
+        "visible": true
+      }
+    },
+    {
+      "parentId": 6,
+      "type": "floatItem",
+      "item": {
+        "numDecimalPlaces": 3,
+        "name": "Float value",
+        "variableName": "GridFloatValue",
+        "id": 9,
+        "eepromAddress": -1,
+        "readOnly": false,
+        "localOnly": false,
+        "visible": true
+      }
+    },
+    {
+      "parentId": 6,
+      "type": "boolItem",
+      "item": {
+        "naming": "TRUE_FALSE",
+        "name": "LED1",
+        "variableName": "GridLED1",
+        "id": 7,
+        "eepromAddress": -1,
+        "readOnly": false,
+        "localOnly": false,
+        "visible": true
+      }
+    },
+    {
+      "parentId": 6,
+      "type": "boolItem",
+      "item": {
+        "naming": "TRUE_FALSE",
+        "name": "LED2",
+        "variableName": "GridLED2",
+        "id": 8,
+        "eepromAddress": -1,
+        "readOnly": false,
+        "localOnly": false,
+        "visible": true
+      }
+    },
+    {
+      "parentId": 6,
+      "type": "actionMenu",
+      "item": {
+        "name": "Up",
+        "variableName": "GridUp",
+        "id": 10,
+        "eepromAddress": -1,
+        "readOnly": false,
+        "localOnly": false,
+        "visible": true
+      }
+    },
+    {
+      "parentId": 6,
+      "type": "actionMenu",
+      "item": {
+        "name": "Down",
+        "variableName": "GridDown",
+        "id": 11,
+        "eepromAddress": -1,
+        "readOnly": false,
+        "localOnly": false,
+        "visible": true
+      }
     }
   ],
   "codeOptions": {
diff --git a/examples/esp32Lcd/esp32Lcd.ino b/examples/esp32Lcd/esp32Lcd.ino
@@ -4,12 +4,10 @@ void setup() {
     Serial.begin(115200);
     Wire.begin(4, 15);
     setupMenu();
-
 }
 
 void loop() {
     taskManager.runLoop();
-
 }
 
 
diff --git a/examples/esp32Lcd/esp32Lcd_menu.cpp b/examples/esp32Lcd/esp32Lcd_menu.cpp
@@ -19,8 +19,22 @@ LiquidCrystalRenderer renderer(lcd, 20, 4);
 
 // Global Menu Item declarations
 
+const PROGMEM AnyMenuInfo minfoGridDown = { "Down", 11, 0xffff, 0, NO_CALLBACK };
+ActionMenuItem menuGridDown(&minfoGridDown, NULL);
+const PROGMEM AnyMenuInfo minfoGridUp = { "Up", 10, 0xffff, 0, NO_CALLBACK };
+ActionMenuItem menuGridUp(&minfoGridUp, &menuGridDown);
+const PROGMEM BooleanMenuInfo minfoGridLED2 = { "LED2", 8, 0xffff, 1, NO_CALLBACK, NAMING_TRUE_FALSE };
+BooleanMenuItem menuGridLED2(&minfoGridLED2, false, &menuGridUp);
+const PROGMEM BooleanMenuInfo minfoGridLED1 = { "LED1", 7, 0xffff, 1, NO_CALLBACK, NAMING_TRUE_FALSE };
+BooleanMenuItem menuGridLED1(&minfoGridLED1, false, &menuGridLED2);
+const PROGMEM FloatMenuInfo minfoGridFloatValue = { "Float value", 9, 0xffff, 3, NO_CALLBACK };
+FloatMenuItem menuGridFloatValue(&minfoGridFloatValue, &menuGridLED1);
+RENDERING_CALLBACK_NAME_INVOKE(fnGridRtCall, backSubItemRenderFn, "Grid", -1, NO_CALLBACK)
+const PROGMEM SubMenuInfo minfoGrid = { "Grid", 6, 0xffff, 0, NO_CALLBACK };
+BackMenuItem menuBackGrid(fnGridRtCall, &menuGridFloatValue);
+SubMenuItem menuGrid(&minfoGrid, &menuBackGrid, NULL);
 RENDERING_CALLBACK_NAME_INVOKE(fnRGBRtCall, rgbAlphaItemRenderFn, "RGB", -1, NO_CALLBACK)
-Rgb32MenuItem menuRGB(5, fnRGBRtCall, false, NULL);
+Rgb32MenuItem menuRGB(5, fnRGBRtCall, false, &menuGrid);
 ListRuntimeMenuItem menuMyList(4, 0, fnMyListRtCall, &menuRGB);
 const PROGMEM BooleanMenuInfo minfoPeeled = { "Power", 3, 0xffff, 1, NO_CALLBACK, NAMING_ON_OFF };
 BooleanMenuItem menuPeeled(&minfoPeeled, false, &menuMyList);
diff --git a/examples/esp32Lcd/esp32Lcd_menu.h b/examples/esp32Lcd/esp32Lcd_menu.h
@@ -30,6 +30,13 @@ extern LiquidCrystalRenderer renderer;
 
 // Global Menu Item exports
 
+extern ActionMenuItem menuGridDown;
+extern ActionMenuItem menuGridUp;
+extern BooleanMenuItem menuGridLED2;
+extern BooleanMenuItem menuGridLED1;
+extern FloatMenuItem menuGridFloatValue;
+extern BackMenuItem menuBackGrid;
+extern SubMenuItem menuGrid;
 extern Rgb32MenuItem menuRGB;
 extern ListRuntimeMenuItem menuMyList;
 extern BooleanMenuItem menuPeeled;
diff --git a/src/MenuHistoryNavigator.h b/src/MenuHistoryNavigator.h
@@ -3,6 +3,11 @@
  * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
  */
 
+/**
+ * @file MenuHistoryNavigator.h contains the functionality to do with menu item navigation, including a stack of
+ * previous navigations
+ */
+
 #ifndef TCMENU_MENUHISTORYNAVIGATOR_H
 #define TCMENU_MENUHISTORYNAVIGATOR_H
 
diff --git a/src/ScrollChoiceMenuItem.h b/src/ScrollChoiceMenuItem.h
@@ -3,6 +3,10 @@
  * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
  */
 
+/**
+ * @file ScrollChoiceMenuItem.h contains the menu item definition for scrolling choice types, and also for RGB items
+ */
+
 #ifndef SCROLL_CHOICE_ENUM_MENU_ITEM_H
 #define SCROLL_CHOICE_ENUM_MENU_ITEM_H
 
diff --git a/src/SecuredMenuPopup.h b/src/SecuredMenuPopup.h
@@ -1,6 +1,10 @@
 #ifndef _SECURED_MENU_POPUP_H_
 #define _SECURED_MENU_POPUP_H_
 
+/**
+ * @file SecuredMenuPopup.h contains the code to show a security screen for secured menus.
+ */
+
 #include <RuntimeMenuItem.h>
 #include <RemoteAuthentication.h>
 
diff --git a/src/graphics/GfxMenuConfig.h b/src/graphics/GfxMenuConfig.h
@@ -3,6 +3,14 @@
  * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
  */
 
+/**
+ * @file GfxMenuConfig.h
+ *
+ * This file contains the base drawing configuration structures and helper methods for
+ * drawing onto graphical screens, be it mono or colour. Also there's some additional
+ * structures for describing colours, coordinates and padding.
+ */
+
 #ifndef _GFX_MENU_CONFIG_H_
 #define _GFX_MENU_CONFIG_H_
 
@@ -11,13 +19,6 @@
 #include "MenuItems.h"
 #include "DrawingPrimitives.h"
 
-/**
- * @file GfxMenuConfig.h
- * 
- * This file contains the base drawing configuration structures and helper methods for
- * drawing onto graphical screens, be it mono or colour. Also there's some additional
- * structures for describing colours, coordinates and padding.
- */
 
 namespace tcgfx {
 
@@ -158,14 +159,29 @@ namespace tcgfx {
         int getRow() const { return rowPosition; }
     };
 
+    /**
+     * A helper function that checks if a particular justification includes the value
+     * @param justification the justification to check
+     * @return true if the value is needed
+     */
     inline bool itemNeedsValue(GridPosition::GridJustification justification) {
         return (justification & GridPosition::CORE_JUSTIFY_VALUE_REQUIRED) != 0;
     }
 
+    /**
+     * A helper function that checks if a particular justification includes the name
+     * @param justification the justification to check
+     * @return true if the name is needed
+     */
     inline bool itemNeedsName(GridPosition::GridJustification justification) {
         return (justification & GridPosition::CORE_JUSTIFY_NAME_REQUIRED) != 0;
     }
 
+    /**
+     * Get the core justification part, eg left, right centre
+     * @param j the justification to check
+     * @return the core part, just left, right centre etc.
+     */
     inline GridPosition::GridJustification coreJustification(GridPosition::GridJustification j) {
         return static_cast<GridPosition::GridJustification>(j & 0b11);
     }
@@ -331,10 +347,40 @@ namespace tcgfx {
      */
     class ItemDisplayPropertiesFactory {
     public:
+        /**
+         * Returns the configuration for the parameters below, it should never return nullptr.
+         * @param pItem the item or null for default
+         * @param compType the component type to get the rendering for
+         * @return the properties for a given component.
+         */
         virtual ItemDisplayProperties* configFor(MenuItem* pItem, ItemDisplayProperties::ComponentType compType) = 0;
+
+        /**
+         * Returns the icon associated with the menu item ID, there are two special IDs for the edit and active icons
+         * @param id the menu item ID or the special ID for edit or active icon
+         * @return the icon or nullptr if not available
+         */
         virtual DrawableIcon* iconForMenuItem(uint16_t id) = 0;
+
+        /**
+         * Get the grid item for a given position if it is available
+         * @param pItem the item to get the grid position for
+         * @return the grid position if available
+         */
         virtual GridPositionWithId* gridPositionForItem(MenuItem* pItem) = 0;
+
+        /**
+         * Get the selected color for a given palette entry
+         * @param colorType
+         * @return
+         */
         virtual color_t getSelectedColor(ItemDisplayProperties::ColorType colorType)  = 0;
+
+        /**
+         * add a new grid position for a given menu item
+         * @param item the menu item the position is for
+         * @param position the position to record
+         */
         virtual void addGridPosition(MenuItem* item, const GridPosition& position)  = 0;
     };
 
diff --git a/src/graphics/GraphicsDeviceRenderer.h b/src/graphics/GraphicsDeviceRenderer.h
@@ -4,7 +4,7 @@
  */
 
 /**
- * @file GraphicsDevice.h the interface that all graphics devices should implement to do the actual graphics rendering.
+ * @file GraphicsDeviceRenderer.h the interface that all graphics devices should implement to do the actual graphics rendering.
  */
 
 #ifndef TCLIBRARYDEV_GRAPHICSDEVICERENDERER_H
diff --git a/src/graphics/MenuTouchScreenEncoder.h b/src/graphics/MenuTouchScreenEncoder.h
@@ -3,6 +3,10 @@
  * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
  */
 
+/**
+ * @file MenuTouchScreenEncoder.h contains the interface between the touch screen and tcMenu.
+ */
+
 #ifndef TCMENU_MENUTOUCHSCREENENCODER_H
 #define TCMENU_MENUTOUCHSCREENENCODER_H
 
diff --git a/src/graphics/RuntimeTitleMenuItem.h b/src/graphics/RuntimeTitleMenuItem.h
@@ -3,15 +3,31 @@
  * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
  */
 
+/**
+ * @file RuntimeTitleMenuItem.h the menu item that is presented for the title
+ */
+
 #ifndef TCMENU_RUNTIMETITLEMENUITEM_H
 #define TCMENU_RUNTIMETITLEMENUITEM_H
 
 #include <BaseRenderers.h>
 
 namespace tcgfx {
 
+    /**
+     * forward reference of the title rendering function
+     * @param item menu item for title
+     * @param mode rendering mode
+     * @param buffer the buffer
+     * @param bufferSize the buffers size
+     * @return status code
+     */
     int appTitleRenderingFn(RuntimeMenuItem *item, uint8_t, RenderFnMode mode, char *buffer, int bufferSize);
 
+    /**
+     * This menu item extension class handles the title row, for the root menu. It stores a header in program memory
+     * and a possible callback function for when it is actioned.
+     */
     class RuntimeTitleMenuItem : public RuntimeMenuItem {
     private:
         const char *titleHeaderPgm;
@@ -40,8 +56,15 @@ namespace tcgfx {
         }
     };
 
+    /**
+     * the global instance of the title menu item
+     */
     extern RuntimeTitleMenuItem appTitleMenuItem;
 
+    /**
+     * Sets the callback that will be triggered when the title is clicked on.
+     * @param cb the title click callback.
+     */
     inline void setTitlePressedCallback(MenuCallbackFn cb) {
         appTitleMenuItem.setCallback(cb);
     }
diff --git a/src/tcMenuVersion.h b/src/tcMenuVersion.h
@@ -3,6 +3,10 @@
  * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
  */
 
+/**
+ * @file TcMenuVersion.h contains the version information and accessor functions.
+ */
+
 #ifndef TCMENU_VERSION_H
 #define TCMENU_VERSION_H
 
@@ -12,8 +16,8 @@ namespace tccore {
 
 // here we define the version as both a string and separate field
 #define TCMENU_MAJOR 2
-#define TCMENU_MINOR 0
-#define TCMENU_PATCH 0
+#define TCMENU_MINOR 1
+#define TCMENU_PATCH 3
 
 /**
  * A helper to generate the major minor version numbers used in the protocol

Original file line number	Diff line number	Diff line change
`@@ -4,12 +4,10 @@ void setup() {`
`4`	`4`	`Serial.begin(115200);`
`5`	`5`	`Wire.begin(4, 15);`
`6`	`6`	`setupMenu();`
`7`		`-`
`8`	`7`	`}`
`9`	`8`
`10`	`9`	`void loop() {`
`11`	`10`	`taskManager.runLoop();`
`12`		`-`
`13`	`11`	`}`
`14`	`12`
`15`	`13`