[PATCH v2] docs: Document camelCase preference for XML elements and attributes
mprivozn at redhat.com
Thu Oct 15 14:19:48 UTC 2020
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 at redhat.com>
Signed-off-by: Michal Privoznik <mprivozn at redhat.com>
diff to v1:
- Extended coding style too.
docs/api_extension.html.in | 6 ++++++
docs/coding-style.rst | 15 +++++++++++++++
2 files changed, 21 insertions(+)
diff --git a/docs/api_extension.html.in b/docs/api_extension.html.in
index 6c64e83314..d7696056ac 100644
@@ -110,6 +110,12 @@
+ Please note that single word names for attributes and elements is
+ preferred. But if you have to use two ore more words please join them in
+ camelCase style.
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 44e5265a60..cfd7b16638 100644
@@ -960,3 +960,18 @@ git):
/* ... 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.
More information about the libvir-list