From da201787092e2934bf20a3232e3398fcef600397 Mon Sep 17 00:00:00 2001 From: Michal Privoznik Date: Thu, 15 Oct 2020 11:30:47 +0200 Subject: [PATCH] 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 Signed-off-by: Michal Privoznik Reviewed-by: Erik Skultety --- 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..e44c1c37b0 100644 --- a/docs/api_extension.html.in +++ b/docs/api_extension.html.in @@ -110,6 +110,12 @@ src/libvirt_public.syms

+

+ Please consult our + coding style + guide on elements and attribute names. +

+

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 --- 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.