doc: Clarify ssize_t use in coding guidelines

Change-Id: I083f673f37495d2e53c704a43a0892231b6eb281
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

diff --git a/docs/coding-guidelines.rst b/docs/coding-guidelines.rst
index 0fb23d962d34d3a84ddda3fe2c9a4f810907220e..3075c63d10eb4aaba91de3d316087202f3bbc4ac 100644 (file)
--- a/docs/coding-guidelines.rst
+++ b/docs/coding-guidelines.rst
@@ -107,7 +107,9 @@ type usage guidelines should be followed:
 
 - Use ``size_t`` when storing the ``sizeof()`` something.
 
-- (Rarely) use ``ssize_t`` when returning ``sizeof()`` or error from a function.
+- Use ``ssize_t`` when returning the ``sizeof()`` something from a function that
+  can also return an error code; the signed type allows for a negative return
+  code in case of error. This practice should be used sparingly.
 
 - Use ``u_register_t`` when it's important to store the contents of a register
   in its native size (32-bit in AArch32 and 64-bit in AArch64). This is not a