From 057b87fdd1e2781611a53d3a6cb7dd67404aca42 Mon Sep 17 00:00:00 2001 From: Yakun Xu Date: Fri, 11 Oct 2024 12:46:44 +0800 Subject: [PATCH] [spinel] parameters untouched on decoding error (#10810) This commit updates the doc of spinel decoder that the parameters are untouched on parsing error. --- src/lib/spinel/spinel_decoder.hpp | 53 ++++++++++++++++--------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/src/lib/spinel/spinel_decoder.hpp b/src/lib/spinel/spinel_decoder.hpp index 8e31a069f..d81e7111a 100644 --- a/src/lib/spinel/spinel_decoder.hpp +++ b/src/lib/spinel/spinel_decoder.hpp @@ -119,7 +119,7 @@ public: * @param[out] aBool Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aBool` is untouched. */ otError ReadBool(bool &aBool); @@ -131,7 +131,7 @@ public: * @param[out] aInt8 Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aInt8` is untouched. */ otError ReadInt8(int8_t &aInt8); @@ -143,7 +143,7 @@ public: * @param[out] aUint8 Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aUint8` is untouched. */ otError ReadUint8(uint8_t &aUint8); @@ -155,7 +155,7 @@ public: * @param[out] aInt16 Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aInt16` is untouched. */ otError ReadInt16(int16_t &aInt16); @@ -167,7 +167,7 @@ public: * @param[out] aUint16 Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aUint16` is untouched. */ otError ReadUint16(uint16_t &aUint16); @@ -179,7 +179,7 @@ public: * @param[out] aInt32 Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `Int32` is untouched. */ otError ReadInt32(int32_t &aInt32); @@ -191,7 +191,7 @@ public: * @param[out] aUint32 Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aUint32` is untouched. */ otError ReadUint32(uint32_t &aUint32); @@ -203,7 +203,7 @@ public: * @param[out] aInt64 Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aInt64` is untouched. */ otError ReadInt64(int64_t &aInt64); @@ -215,7 +215,7 @@ public: * @param[out] aUint64 Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aUint64` is untouched. */ otError ReadUint64(uint64_t &aUint64); @@ -227,7 +227,7 @@ public: * @param[out] aUint Reference to variable to output the read value. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aUint` is untouched. */ otError ReadUintPacked(unsigned int &aUint); @@ -240,7 +240,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aIp6AddrPtr` is untouched. */ otError ReadIp6Address(const spinel_ipv6addr_t *&aIp6AddrPtr) { @@ -256,7 +256,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aIp6AddrPtr` is untouched. */ otError ReadIp6Address(const otIp6Address *&aIp6AddrPtr) { @@ -272,7 +272,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aIp6AddrBufPtr` is untouched. */ otError ReadIp6Address(const uint8_t *&aIp6AddrBufPtr) { @@ -288,7 +288,7 @@ public: * On success, the address is copied into the output variable. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aIp6Addr` is untouched. */ otError ReadIp6Address(spinel_ipv6addr_t &aIp6Addr); @@ -301,7 +301,7 @@ public: * On success, the address is copied into the output variable. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aIp6Addr` is untouched. */ otError ReadIp6Address(otIp6Address &aIp6Addr); @@ -314,7 +314,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aEui64Ptr` is untouched. */ otError ReadEui64(const spinel_eui64_t *&aEui64Ptr) { @@ -330,7 +330,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aEui64Ptr` is untouched. */ otError ReadEui64(const otExtAddress *&aEui64Ptr) { @@ -346,7 +346,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aEui64BufPtr` is untouched. */ otError ReadEui64(const uint8_t *&aEui64BufPtr) { return ReadItem(&aEui64BufPtr, sizeof(spinel_eui64_t)); } @@ -359,7 +359,7 @@ public: * On success, the address is copied into the output variable. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aEui64` is untouched. */ otError ReadEui64(spinel_eui64_t &aEui64); @@ -372,7 +372,7 @@ public: * On success, the address is copied into the output variable. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aEui64` is untouched. */ otError ReadEui64(otExtAddress &aEui64); @@ -385,7 +385,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aEui48Ptr` is untouched. */ otError ReadEui48(const spinel_eui48_t *&aEui48Ptr) { @@ -401,7 +401,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aEui48BufPtr` is untouched.. */ otError ReadEui48(const uint8_t *&aEui48BufPtr) { return ReadItem(&aEui48BufPtr, sizeof(spinel_eui48_t)); } @@ -414,7 +414,7 @@ public: * On success, value is copied into the output variable. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aEui48` is untouched. */ otError ReadEui48(spinel_eui48_t &aEui48); @@ -427,7 +427,7 @@ public: * On success, the pointer variable is updated. * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value and `aUtf8` is untouched. */ otError ReadUtf8(const char *&aUtf8); @@ -441,7 +441,7 @@ public: * @param[out] aDataLen Reference to variable to output the data length (number of bytes). * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value. `aData` and `aDataLen` are untouched. */ otError ReadData(const uint8_t *&aData, uint16_t &aDataLen); @@ -457,7 +457,8 @@ public: * @param[out] aDataLen Reference to variable to out the data length (number of bytes). * * @retval OT_ERROR_NONE Successfully read the value. - * @retval OT_ERROR_PARSE Failed to parse/decode the value. + * @retval OT_ERROR_PARSE Failed to parse/decode the value. `aDataLen` may be updated and `aData` is + * untouched. */ otError ReadDataWithLen(const uint8_t *&aData, uint16_t &aDataLen);