Improve documentation and member names for ChipZclRawBuffer_t.

[bzbarsky-apple]

Also fixes a memory leak in chipZclProcessIncoming that became more obvious
with the new documentation.

Problem

It wasn't immediately clear to me what some of the ChipZclRawBuffer_t APIs did.

Summary of Changes

Documentation improvements, memory leak fix.

fixes #856

[woody-apple]

Can we doxygen headers?

[bzbarsky-apple]

Can we doxygen headers?

We can, and this header already uses comments in the general format doxygen recognizes. @woody-apple are you just looking for @param bits in function documentation, or something else?

[bhaskar-apple]

LGTM

[woody-apple]

@gerickson @jelderton ?

[bzbarsky-apple]

@turon The test failure is:

Failed assert: Tdelta < (Tdelay + margin) in ../../../../../src/platform/tests/TestPlatformTime.cpp:116

That doesn't seem related to these changes. Is that test known to intermittently fail?

[woody-apple]

@turon The test failure is:

Failed assert: Tdelta < (Tdelay + margin) in ../../../../../src/platform/tests/TestPlatformTime.cpp:116

That doesn't seem related to these changes. Is that test known to intermittently fail?

#861

[gerickson]

Thanks for doing this. The only additional request for a future pass would be decorating the @param declarations with [in], [out], or [inout] to document their directionality. Clearly, if they aren't pointers or references they must by definition be [in]; however, I think it'd be good for our Doxygen to be consistent across the board on that decoration.

[rwalker-apple]

any reason for these to be allocated instead of just placed on the stack?

[bzbarsky-apple]

That is a good question; I mostly kept the existing setup there, but I agree that in general it would make a lot of sense to me to put the context and the buffer on the stack...

[rwalker-apple]

fixed in #898

[bzbarsky-apple]

The only additional request for a future pass would be decorating the @param declarations with [in], [out], or [inout]

#897 does that.