[PATCH v2] docs: Document camelCase preference for XML elements and attributes

Michal Privoznik posted 1 patch 1 week ago
Test syntax-check failed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/libvirt tags/patchew/f781b154881d884b620e3e66a0b9e072ae8b8f6a.1602771551.git.mprivozn@redhat.com
docs/api_extension.html.in |  6 ++++++
docs/coding-style.rst      | 15 +++++++++++++++
2 files changed, 21 insertions(+)

[PATCH v2] docs: Document camelCase preference for XML elements and attributes

Posted by Michal Privoznik 1 week ago
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>
---

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

Re: [PATCH v2] docs: Document camelCase preference for XML elements and attributes

Posted by Erik Skultety 1 week ago
On Thu, Oct 15, 2020 at 04:19:48PM +0200, Michal Privoznik wrote:
> 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>
> ---
> 
> 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>

Hmm, I think it would be worth more if you just linked the coding style page
^here so that we cover all the conventions rather than a single one.

With that addressed, there's no need for v3:
Reviewed-by: Erik Skultety <eskultet@redhat.com>