docs: Document camelCase preference for XML elements and attributes

Recently I've merged a patch that used hyphens in an attribute
name. I fixed it later, but turned out we don't document our
preference which is camelCase.

Suggested-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>

diff --git a/docs/api_extension.html.in b/docs/api_extension.html.in
index 6c64e83314a367f7589e4b2abdff729debb176ff..e44c1c37b0366c6d3abdad362f3712796e98c2ae 100644 (file)
--- a/docs/api_extension.html.in
+++ b/docs/api_extension.html.in
@@ -110,6 +110,12 @@
         src/libvirt_public.syms
     </code></p>
 
+    <p>
+      Please consult our
+      <a href="coding-style.html#xml-element-and-attribute-naming">coding style</a>
+      guide on elements and attribute names.
+    </p>
+
     <p>
       This task is in many ways the most important to get right, since once
       the API has been committed to the repository, it's libvirt's policy

diff --git a/docs/coding-style.rst b/docs/coding-style.rst
index 44e5265a6042124a7d25b698ffa2a83f9cae265a..cfd7b166389decff0b5e651fc073050ed49434e1 100644 (file)
--- a/docs/coding-style.rst
+++ b/docs/coding-style.rst
@@ -960,3 +960,18 @@ git):
    cleanup:
       /* ... do other stuff ... */
   }
+
+
+XML element and attribute naming
+--------------------------------
+
+New elements and/or attributes should be short and descriptive.
+In general, they should reflect what the feature does instead of
+how exactly it is named in given hypervisor because this creates
+an abstraction that other drivers can benefit from (for instance
+if the same feature is named differently in two hypervisors).
+That is not to say an element or attribute can't have the same
+name as in a hypervisor, but proceed with caution.
+
+Single worded names are preferred, but if more words must be
+used then they shall be joined in camelCase style.