[PATCH v2 1/2] docs: Format bit shift and hex notation for bitwise flag enums

[Peter Krempa <pkrempa@xxxxxxxxxx>]

Big number itself does not make much sense in some cases. Format the
bitshift format as well.

Changes our web page docs from:

VIR_MIGRATE_POSTCOPY = 32768 : Setting the VIR_MIGRATE_POSTCOPY...
VIR_MIGRATE_TLS      = 65536 : Setting the VIR_MIGRATE_TLS flag...

to:

VIR_MIGRATE_POSTCOPY = 32768 (0x8000; 1 << 15)  : Setting the VIR_MIGRATE_POSTCOPY...
VIR_MIGRATE_TLS      = 65536 (0x10000; 1 << 16) : Setting the VIR_MIGRATE_TLS flag...

Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 docs/apibuild.py | 10 ++++++++++
 docs/libvirt.css |  4 ++++
 docs/newapi.xsl  | 22 ++++++++++++++++++++--
 3 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/docs/apibuild.py b/docs/apibuild.py
index 3ef5d0f554..9e04871220 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -2117,12 +2117,22 @@ class docBuilder:
                      self.modulename_file(id.header)))
         if id.info is not None:
             info = id.info
+            valhex = ""
             if info[0] is not None and info[0] != '':
                 try:
                     val = eval(info[0])
+                    valhex = hex(val)
                 except:
                     val = info[0]
                 output.write(" value='%s'" % (val))
+
+                if valhex != "":
+                    output.write(" value_hex='%s'" % (valhex))
+
+                m = re.match("\(?1<<(\d+)\)?", info[0])
+                if m:
+                    output.write(" value_bitshift='%s'" % (m.group(1)))
+
             if info[2] is not None and info[2] != '':
                 output.write(" type='%s'" % info[2])
             if info[1] is not None and info[1] != '':
diff --git a/docs/libvirt.css b/docs/libvirt.css
index e590b33cfb..c5fe27fa3f 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -537,3 +537,7 @@ dl.mail dt a:hover {
     color:  rgb(255, 230, 0);
     text-decoration: none;
 }
+
+td.enumvalue {
+    white-space: nowrap;
+}
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 8d4c032c03..c808fe5ff8 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -288,6 +288,24 @@
     </xsl:choose>
   </xsl:template>

+  <xsl:template name="enumvalue">
+    <xsl:param name="value" select="@value"/>
+    <xsl:param name="valuehex" select="@value_hex"/>
+    <xsl:param name="valuebitshift" select="@value_bitshift"/>
+    <xsl:value-of select="@value"/>
+    <xsl:if test="$valuehex != '' or $valuebitshift != ''">
+      <xsl:text> (</xsl:text>
+      <xsl:if test="$valuehex != ''">
+        <xsl:value-of select="@value_hex"/>
+      </xsl:if>
+      <xsl:if test="$valuebitshift != ''">
+        <xsl:text>; 1 &lt;&lt; </xsl:text>
+        <xsl:value-of select="@value_bitshift"/>
+      </xsl:if>
+      <xsl:text>)</xsl:text>
+    </xsl:if>
+  </xsl:template>
+
   <xsl:template match="typedef[@type = 'enum']">
     <xsl:variable name="name" select="string(@name)"/>
     <h3><a name="{$name}"><code><xsl:value-of select="$name"/></code></a></h3>
@@ -306,7 +324,7 @@
             <td><xsl:text> = </xsl:text></td>
             <xsl:choose>
               <xsl:when test="@info != ''">
-                <td><xsl:value-of select="@value"/></td>
+                <td class="enumvalue"><xsl:call-template name="enumvalue"/></td>
                 <td>
                   <div class="comment">
                     <xsl:call-template name="dumptext">
@@ -316,7 +334,7 @@
                 </td>
               </xsl:when>
               <xsl:otherwise>
-                <td colspan="2"><xsl:value-of select="@value"/></td>
+                <td colspan="2" class="enumvalue"><xsl:call-template name="enumvalue"/></td>
               </xsl:otherwise>
             </xsl:choose>
           </tr>
-- 
2.20.1

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list