Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
---
 docs/coding-style.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/coding-style.rst b/docs/coding-style.rst
index 470c61860f..dca9de1915 100644
--- a/docs/coding-style.rst
+++ b/docs/coding-style.rst
@@ -54,6 +54,7 @@ Struct type names
    and each following word should have its first letter in
    uppercase. The struct name should be the same as the typedef
    name with a leading underscore.
+
    ::
 
      typedef struct _virHashTable virHashTable;
@@ -61,6 +62,10 @@ Struct type names
          ...
      };
 
+   Historically, libvirt declared pointer types 'virXXXPtr' for
+   both public and internal types. Do not introduce new such
+   typedefs for internal types.
+
 Function names
    All functions should have a 'vir' prefix in their name,
    followed by one or more words with first letter of each word
-- 
2.31.1

On a Friday in 2022, Tim Wiederhake wrote:
>Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
>---
> docs/coding-style.rst | 5 +++++
> 1 file changed, 5 insertions(+)
>
>diff --git a/docs/coding-style.rst b/docs/coding-style.rst
>index 470c61860f..dca9de1915 100644
>--- a/docs/coding-style.rst
>+++ b/docs/coding-style.rst
>@@ -54,6 +54,7 @@ Struct type names
>    and each following word should have its first letter in
>    uppercase. The struct name should be the same as the typedef
>    name with a leading underscore.
>+
>    ::
>
>      typedef struct _virHashTable virHashTable;
>@@ -61,6 +62,10 @@ Struct type names
>          ...
>      };
>
>+   Historically, libvirt declared pointer types 'virXXXPtr' for
>+   both public and internal types. Do not introduce new such
>+   typedefs for internal types.
>+

This weakly suggests that they should be introduced for new public
types. I have no preference, but I think we should mention it here
if we're mentioning internal types.

Jano

> Function names
>    All functions should have a 'vir' prefix in their name,
>    followed by one or more words with first letter of each word
>-- 
>2.31.1
>

On Fri, Jan 14, 2022 at 04:43:58PM +0100, Ján Tomko wrote:
> On a Friday in 2022, Tim Wiederhake wrote:
> > Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
> > ---
> > docs/coding-style.rst | 5 +++++
> > 1 file changed, 5 insertions(+)
> >
> > diff --git a/docs/coding-style.rst b/docs/coding-style.rst
> > index 470c61860f..dca9de1915 100644
> > --- a/docs/coding-style.rst
> > +++ b/docs/coding-style.rst
> > @@ -54,6 +54,7 @@ Struct type names
> >    and each following word should have its first letter in
> >    uppercase. The struct name should be the same as the typedef
> >    name with a leading underscore.
> > +
> >    ::
> >
> >      typedef struct _virHashTable virHashTable;
> > @@ -61,6 +62,10 @@ Struct type names
> >          ...
> >      };
> >
> > +   Historically, libvirt declared pointer types 'virXXXPtr' for
> > +   both public and internal types. Do not introduce new such
> > +   typedefs for internal types.
>
> This weakly suggests that they should be introduced for new public
> types. I have no preference, but I think we should mention it here
> if we're mentioning internal types.

-- 
Andrea Bolognani / Red Hat / Virtualization

On Fri, Jan 14, 2022 at 04:43:58PM +0100, Ján Tomko wrote:
> On a Friday in 2022, Tim Wiederhake wrote:
> > +   Historically, libvirt declared pointer types 'virXXXPtr' for
> > +   both public and internal types. Do not introduce new such
> > +   typedefs for internal types.
>
> This weakly suggests that they should be introduced for new public
> types. I have no preference, but I think we should mention it here
> if we're mentioning internal types.

Agreed. More specifically, I think we should encourage defining the
Ptr alias for public types because, much as I dislike their
existence, having a mix of both conventions in the public API would
be IMO worse than sticking with the status quo.

-- 
Andrea Bolognani / Red Hat / Virtualization

On Fri, Jan 14, 2022 at 09:24:23AM -0800, Andrea Bolognani wrote:
> On Fri, Jan 14, 2022 at 04:43:58PM +0100, Ján Tomko wrote:
> > On a Friday in 2022, Tim Wiederhake wrote:
> > > +   Historically, libvirt declared pointer types 'virXXXPtr' for
> > > +   both public and internal types. Do not introduce new such
> > > +   typedefs for internal types.
> >
> > This weakly suggests that they should be introduced for new public
> > types. I have no preference, but I think we should mention it here
> > if we're mentioning internal types.
> 
> Agreed. More specifically, I think we should encourage defining the
> Ptr alias for public types because, much as I dislike their
> existence, having a mix of both conventions in the public API would
> be IMO worse than sticking with the status quo.

Yes, the public API must carry on using its existing practice. Only
the internal usage is eliminated.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|