[PATCH v2] 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(a)redhat.com&gt; Signed-off-by: Michal Privoznik <mprivozn(a)redhat.com&gt; --- 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 --- a/docs/api_extension.html.in +++ b/docs/api_extension.html.in @@ -110,6 +110,12 @@ src/libvirt_public.syms </code></p> + <p> + 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. + </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 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. -- 2.26.2