[Qemu-devel] [PATCH] HACKING: Clarify the paragraph about typedefs

[Thomas Huth <thuth@redhat.com>]

The paragraph about typedefs is very sparse and caused some trouble
already: Is this mandatory coding style or just a recommendation?
... since this is the HACKING file and not in CODING_STYLE. And various
versions of GCC and Clang disallow duplicated typedefs in certain
language modes, so the "enforced" typedeffing repeatedly caused
compile errors in the past.
Thus let's reword this paragraph a little bit, so that it is clear
that typedefs are welcome, but not a mandatory coding style. Also
add some information about our include/qemu/typedefs.h file here
since most newcomers are not aware of this file yet.

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 HACKING | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/HACKING b/HACKING
index 0fc3e0f..aa6fc3f 100644
--- a/HACKING
+++ b/HACKING
@@ -100,7 +100,13 @@ pointer, you're guaranteed that it is used to modify the storage
 it points to, or it is aliased to another pointer that is.
 
 2.3. Typedefs
-Typedefs are used to eliminate the redundant 'struct' keyword.
+Typedefs can be used to eliminate the redundant 'struct' keyword. This is
+especially helpful for common types that are used all over the place. Since
+certain C compilers choke on duplicated typedefs, you should avoid them and
+declare a typedef only in one header file. For common types, you can use
+"include/qemu/typedefs.h" for example. Note that it is also perfectly fine to
+use forward struct definitions without typedefs for references in headers
+to avoid the problem with duplicated typedefs.
 
 2.4. Reserved namespaces in C and POSIX
 Underscore capital, double underscore, and underscore 't' suffixes should be
-- 
1.8.3.1