Add code safety comments for methods that could return junk if the get fails

Author: PaulZC

src/u-blox_GNSS.h

@@ -386,14 +386,15 @@ class DevUBLOXGNSS
   bool setDGNSSConfiguration(sfe_ublox_dgnss_mode_e dgnssMode = SFE_UBLOX_DGNSS_MODE_FIXED, uint8_t layer = VAL_LAYER_RAM_BBR, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Set the DGNSS differential mode
 
   // Read the module's protocol version
+  // For safety, call getProtocolVersion etc. inside an if(getModuleInfo())
   uint8_t getProtocolVersionHigh(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returns the PROTVER XX.00 from UBX-MON-VER register
   uint8_t getProtocolVersionLow(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);  // Returns the PROTVER 00.XX from UBX-MON-VER register
   uint8_t getFirmwareVersionHigh(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returns the FWVER XX.00 from UBX-MON-VER register
   uint8_t getFirmwareVersionLow(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);  // Returns the FWVER 00.XX from UBX-MON-VER register
   const char *getFirmwareType(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);    // Returns the firmware type (SPG, HPG, ADR, etc.) from UBX-MON-VER register
   const char *getModuleName(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);      // Returns the module name (ZED-F9P, ZED-F9R, etc.) from UBX-MON-VER register
   bool getProtocolVersion(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);        // Deprecated. Use getModuleInfo.
-  bool getModuleInfo(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);             // Queries module, extracts info
+  bool getModuleInfo(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);             // Queries module, extracts info. Returns true if MON-VER was read successfully
 protected:
   bool prepareModuleInfo(uint16_t maxWait);
 
@@ -1078,6 +1079,7 @@ class DevUBLOXGNSS
   uint16_t getNavigationRate(uint8_t layer = VAL_LAYER_RAM, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);                       // Unsafe overload
 
   // Helper functions for DOP
+  // For safety, call these inside an if(getDOP())
 
   uint16_t getGeometricDOP(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
   uint16_t getPositionDOP(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
@@ -1088,12 +1090,14 @@ class DevUBLOXGNSS
   uint16_t getEastingDOP(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
 
   // Helper functions for ATT
+  // For safety, call these inside an if(getNAVATT())
 
   float getATTroll(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);    // Returned as degrees
   float getATTpitch(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);   // Returned as degrees
   float getATTheading(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returned as degrees
 
   // Helper functions for PVT
+  // For safety, call these inside an if(getPVT())
 
   uint32_t getTimeOfWeek(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
   uint16_t getYear(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
@@ -1145,6 +1149,7 @@ class DevUBLOXGNSS
   int32_t getGeoidSeparation(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
 
   // Helper functions for HPPOSECEF
+  // For safety, call these inside an if(getNAVHPPOSECEF())
 
   uint32_t getPositionAccuracy(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returns the 3D accuracy of the current high-precision fix, in mm. Supported on NEO-M8P, ZED-F9P,
   int32_t getHighResECEFX(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);      // Returns the ECEF X coordinate (cm)
@@ -1155,6 +1160,7 @@ class DevUBLOXGNSS
   int8_t getHighResECEFZHp(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);     // Returns the ECEF Z coordinate High Precision Component (0.1 mm)
 
   // Helper functions for HPPOSLLH
+  // For safety, call these inside an if(getHPPOSLLH())
 
   uint32_t getTimeOfWeekFromHPPOSLLH(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
   int32_t getHighResLongitude(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
@@ -1169,13 +1175,15 @@ class DevUBLOXGNSS
   uint32_t getVerticalAccuracy(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
 
   // Helper functions for PVAT
+  // For safety, call these inside an if(getNAVPVAT())
 
   int32_t getVehicleRoll(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);    // Returns vehicle roll in degrees * 10^-5
   int32_t getVehiclePitch(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);   // Returns vehicle pitch in degrees * 10^-5
   int32_t getVehicleHeading(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returns vehicle heading in degrees * 10^-5
   int32_t getMotionHeading(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);  // Returns the motion heading in degrees * 10^-5
 
   // Helper functions for SVIN
+  // For safety, call these inside an if(getSurveyStatus())
 
   bool getSurveyInActive(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
   bool getSurveyInValid(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
@@ -1184,11 +1192,13 @@ class DevUBLOXGNSS
   float getSurveyInMeanAccuracy(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);           // Returned as m
 
   // Helper functions for TIMELS
+  // For safety, call these inside an if(getLeapSecondEvent())
 
   uint8_t getLeapIndicator(int32_t &timeToLsEvent, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
   int8_t getCurrentLeapSeconds(sfe_ublox_ls_src_e &source, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);
 
   // Helper functions for RELPOSNED
+  // For safety, call these inside an if(getRELPOSNED())
 
   float getRelPosN(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);    // Returned as m
   float getRelPosE(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);    // Returned as m
@@ -1198,24 +1208,28 @@ class DevUBLOXGNSS
   float getRelPosAccD(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returned as m
 
   // Helper functions for AOPSTATUS
+  // For safety, call these inside an if(getAOPSTATUS())
 
   uint8_t getAOPSTATUSuseAOP(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returns the UBX-NAV-AOPSTATUS useAOP flag. Don't confuse this with getAopCfg - which returns the aopCfg byte from UBX-CFG-NAVX5
   uint8_t getAOPSTATUSstatus(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returns the UBX-NAV-AOPSTATUS status field. A host application can determine the optimal time to shut down the receiver by monitoring the status field for a steady 0.
 
   // Helper functions for TIM TP
+  // For safety, call these inside an if(getTIMTP())
 
   uint32_t getTIMTPtowMS(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);                          // Returns the UBX-TIM-TP towMS time pulse of week (ms)
   uint32_t getTIMTPtowSubMS(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);                       // Returns the UBX-TIM-TP submillisecond part of towMS (ms * 2^-32)
   uint16_t getTIMTPweek(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);                           // Returns the UBX-TIM-TP time pulse week according to time base
   uint32_t getTIMTPAsEpoch(uint32_t &microsecond, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Convert TIM TP to Unix Epoch - CAUTION! Assumes the time base is UTC and the week number is GPS
 
   // Helper function for hardware status (including jamming)
+  // For safety, call getAntennaStatus inside an if(getMONHW())
 
   bool getHWstatus(UBX_MON_HW_data_t *data = nullptr, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Get the hardware status using UBX_MON_HW
   sfe_ublox_antenna_status_e getAntennaStatus(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);         // Get the antenna status (aStatus) using UBX_MON_HW
 
 #ifndef SFE_UBLOX_DISABLE_ESF
   // Helper functions for ESF
+  // For safety, call getESFroll/pitch/yaw inside an if(getESFALG())
 
   float getESFroll(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);  // Returned as degrees
   float getESFpitch(uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returned as degrees
@@ -1228,6 +1242,7 @@ class DevUBLOXGNSS
 
 #ifndef SFE_UBLOX_DISABLE_HNR
   // Helper functions for HNR
+  // For safety, call getHNRroll/pitch/yaw inside an if(getHNRATT())
 
   bool setHNRNavigationRate(uint8_t rate, uint8_t layer = VAL_LAYER_RAM_BBR, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait); // Returns true if the setHNRNavigationRate is successful
   uint8_t getHNRNavigationRate(uint8_t layer = VAL_LAYER_RAM, uint16_t maxWait = kUBLOXGNSSDefaultMaxWait);                // Returns 0 if the getHNRNavigationRate fails