[PATCH] 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/2021e73d1cb9fb1859222f74470db24acddeed4d.1602754398.git.mprivozn@redhat.com
docs/api_extension.html.in | 6 ++++++
1 file changed, 6 insertions(+)

[PATCH] 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>
---

I'm not sure this is the correct place to put this, suggestions welcome.

 docs/api_extension.html.in | 6 ++++++
 1 file changed, 6 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
-- 
2.26.2

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

Posted by Erik Skultety 1 week ago
On Thu, Oct 15, 2020 at 11:34:39AM +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>
> ---
> 
> I'm not sure this is the correct place to put this, suggestions welcome.
> 
>  docs/api_extension.html.in | 6 ++++++
>  1 file changed, 6 insertions(+)

I perceive api_extension as an overall guideline what a patch series should
look like if you plan on introducing a new API/feature. I still think that XML
attribute naming counts as style convention just like the if-else block
formatting, spacing, indentation, etc.

Erik