From e2fe13ab41bb9d26b01e256675454999fc99e537 Mon Sep 17 00:00:00 2001 From: Boris Zbarsky Date: Tue, 25 Jan 2022 12:38:14 -0500 Subject: [PATCH] Clarify AttributeAccessInferface documentation (#13878) * Clarify AttributeAccessInferface documentation * Apply suggestions from code review Co-authored-by: Tennessee Carmel-Veilleux Co-authored-by: Tennessee Carmel-Veilleux --- src/app/AttributeAccessInterface.h | 36 ++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/src/app/AttributeAccessInterface.h b/src/app/AttributeAccessInterface.h index 983c15c975c49b..6825cf9018df69 100644 --- a/src/app/AttributeAccessInterface.h +++ b/src/app/AttributeAccessInterface.h @@ -352,12 +352,18 @@ class AttributeAccessInterface * * @param [in] aPath indicates which exact data is being read. * @param [in] aEncoder the AttributeValueEncoder to use for encoding the - * data. If this function returns scucess and no attempt is - * made to encode data using aEncoder, the - * AttributeAccessInterface did not try to provide any data. In - * this case, normal attribute access will happen for the read. - * This may involve reading from the attribute store or external - * attribute callbacks. + * data. + * + * The implementation can do one of three things: + * + * 1) Return a failure. This is treated as a failed read and the error is + * returned to the client, by converting it to a StatusIB. + * 2) Return success and attempt to encode data using aEncoder. The data is + * returned to the client. + * 3) Return success and not attempt to encode any data using aEncoder. In + * this case, Ember attribute access will happen for the read. This may + * involve reading from the attribute store or external attribute + * callbacks. */ virtual CHIP_ERROR Read(const ConcreteReadAttributePath & aPath, AttributeValueEncoder & aEncoder) = 0; @@ -366,12 +372,18 @@ class AttributeAccessInterface * * @param [in] aPath indicates which exact data is being written. * @param [in] aDecoder the AttributeValueDecoder to use for decoding the - * data. If this function returns scucess and no attempt is - * made to decode data using aDecoder, the - * AttributeAccessInterface did not try to write any data. In - * this case, normal attribute access will happen for the write. - * This may involve writing to the attribute store or external - * attribute callbacks. + * data. + * + * The implementation can do one of three things: + * + * 1) Return a failure. This is treated as a failed write and the error is + * sent to the client, by converting it to a StatusIB. + * 2) Return success and attempt to decode from aDecoder. This is + * treated as a successful write. + * 3) Return success and not attempt to decode from aDecoder. In + * this case, Ember attribute access will happen for the write. This may + * involve writing to the attribute store or external attribute + * callbacks. */ virtual CHIP_ERROR Write(const ConcreteDataAttributePath & aPath, AttributeValueDecoder & aDecoder) { return CHIP_NO_ERROR; }