docs: coding-style: Clarify on virXXXPtr types

This partially reverts commit 9ccbed6afb.

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>

diff --git a/docs/coding-style.rst b/docs/coding-style.rst
index 37e6009db4122873909620356f361af051a5e2ef..af928a16c03011ada84db7f2bb867c6ec01b57e6 100644 (file)
--- a/docs/coding-style.rst
+++ b/docs/coding-style.rst
@@ -53,11 +53,16 @@ Struct type names
    All structs should have a 'vir' prefix in their typedef name,
    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.
+   name with a leading underscore. For types that are part of the
+   public API, a second typedef should be given for a pointer to
+   the struct with a 'Ptr' suffix. Do not introduce new such
+   typedefs for internal types.
+
    ::
 
-     typedef struct _virHashTable virHashTable;
-     struct _virHashTable {
+     typedef struct _virSomeType virSomeType;
+     typedef virSomeType *virSomeTypePtr;
+     struct _virSomeType {
          ...
      };
 
@@ -69,8 +74,8 @@ Function names
    name prefix should match the object typedef name, otherwise it
    should match the filename. Following this comes the verb /
    action name, and finally an optional subject name. For example,
-   given an object 'virHashTable', all functions should have a
-   name 'virHashTable$VERB' or 'virHashTable$VERB$SUBJECT", e.g.
+   given an object 'virSomeType', all functions should have a
+   name 'virSomeType$VERB' or 'virSomeType$VERB$SUBJECT", e.g.
    'virHashTableLookup' or 'virHashTableGetValue'.
 
 Macro names