[Qemu-devel] [PATCH v2] HACKING: Document 'struct' keyword usage

Eduardo Habkost posted 1 patch 16 weeks ago
Test FreeBSD passed
Test docker-mingw@fedora passed
Test asan passed
Test docker-clang@ubuntu passed
Test checkpatch passed
Test s390x passed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20190812234630.22814-1-ehabkost@redhat.com
HACKING | 14 +++++++++++++-
1 file changed, 13 insertions(+), 1 deletion(-)

[Qemu-devel] [PATCH v2] HACKING: Document 'struct' keyword usage

Posted by Eduardo Habkost 16 weeks ago
Sometimes we use the 'struct' keyword in headers to help us
reduce dependencies between header files.  Document that
practice.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
Changes v1 -> v2:
* Use paragraphs written by Paolo Bonzini at
  https://www.mail-archive.com/qemu-devel@nongnu.org/msg586214.html
* Fix typos spotted by Thomas Huth
---
 HACKING | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/HACKING b/HACKING
index 0fc3e0fc04..035276e668 100644
--- a/HACKING
+++ b/HACKING
@@ -100,7 +100,19 @@ 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 are used to eliminate the redundant 'struct' keyword, since type
+names have a different style than other identifiers ("CamelCase" versus
+"snake_case").  Each struct should have a CamelCase name and a
+corresponding typedef.
+
+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.  However, as a matter
+of convenience it is also perfectly fine to use forward struct
+definitions instead of typedefs in headers and function prototypes; this
+avoids problems with duplicated typedefs and reduces the need to include
+headers from other headers.
 
 2.4. Reserved namespaces in C and POSIX
 Underscore capital, double underscore, and underscore 't' suffixes should be
-- 
2.21.0


Re: [Qemu-devel] [PATCH v2] HACKING: Document 'struct' keyword usage

Posted by Thomas Huth 16 weeks ago
On 8/13/19 1:46 AM, Eduardo Habkost wrote:
> Sometimes we use the 'struct' keyword in headers to help us
> reduce dependencies between header files.  Document that
> practice.
> 
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
> Changes v1 -> v2:
> * Use paragraphs written by Paolo Bonzini at
>   https://www.mail-archive.com/qemu-devel@nongnu.org/msg586214.html
> * Fix typos spotted by Thomas Huth
> ---
>  HACKING | 14 +++++++++++++-
>  1 file changed, 13 insertions(+), 1 deletion(-)
> 
> diff --git a/HACKING b/HACKING
> index 0fc3e0fc04..035276e668 100644
> --- a/HACKING
> +++ b/HACKING
> @@ -100,7 +100,19 @@ 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 are used to eliminate the redundant 'struct' keyword, since type
> +names have a different style than other identifiers ("CamelCase" versus
> +"snake_case").  Each struct should have a CamelCase name and a

Maybe s/Each struct/Each global struct/ ? Or "non-local" or something
similar? Sometimes, you also define a struct just within a function, and
in that case we don't require the typedef, do we?

> +corresponding typedef.
> +
> +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.  However, as a matter
> +of convenience it is also perfectly fine to use forward struct
> +definitions instead of typedefs in headers and function prototypes; this
> +avoids problems with duplicated typedefs and reduces the need to include
> +headers from other headers.

Reviewed-by: Thomas Huth <thuth@redhat.com>

Re: [Qemu-devel] [PATCH v2] HACKING: Document 'struct' keyword usage

Posted by Paolo Bonzini 16 weeks ago
On 13/08/19 08:44, Thomas Huth wrote:
> Maybe s/Each struct/Each global struct/ ? Or "non-local" or something
> similar? Sometimes, you also define a struct just within a function, and
> in that case we don't require the typedef, do we?

I changed it to "each named struct" and queued.

Thanks,

Paolo