From 12996dd458ed5ca024636092b1e44ae0ad3324c1 Mon Sep 17 00:00:00 2001
From: Cole Robinson <crobinso@redhat.com>
Date: Tue, 3 Apr 2018 11:03:32 -0400
Subject: [PATCH] domcapabilities: Document class layout a bit

It's a bit weird due to the repetitive nature of domainCapabilities
XML layout
---
 virtinst/domcapabilities.py | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/virtinst/domcapabilities.py b/virtinst/domcapabilities.py
index ce5765b1..84b8e432 100644
--- a/virtinst/domcapabilities.py
+++ b/virtinst/domcapabilities.py
@@ -12,6 +12,10 @@ import re
 from .xmlbuilder import XMLBuilder, XMLChildProperty, XMLProperty
 
 
+########################################
+# Genering <enum> and <value> handling #
+########################################
+
 class _Value(XMLBuilder):
     XML_NAME = "value"
     value = XMLProperty(".")
@@ -42,12 +46,31 @@ class _CapsBlock(_HasValues):
 
 
 def _make_capsblock(xml_root_name):
+    """
+    Build a class object representing a list of <enum> in the XML. For
+    example, domcapabilities may have a block like:
+
+    <graphics supported='yes'>
+      <enum name='type'>
+        <value>sdl</value>
+        <value>vnc</value>
+        <value>spice</value>
+      </enum>
+    </graphics>
+
+    To build a class that tracks that whole <graphics> block, call this
+    like _make_capsblock("graphics")
+    """
     class TmpClass(_CapsBlock):
         pass
     setattr(TmpClass, "XML_NAME", xml_root_name)
     return TmpClass
 
 
+#############################
+# Misc toplevel XML classes #
+#############################
+
 class _OS(_CapsBlock):
     XML_NAME = "os"
     loader = XMLChildProperty(_make_capsblock("loader"), is_single=True)
@@ -64,6 +87,9 @@ class _Features(_CapsBlock):
     gic = XMLChildProperty(_make_capsblock("gic"), is_single=True)
 
 
+###############
+# CPU classes #
+###############
 
 class _CPUModel(XMLBuilder):
     XML_NAME = "model"
@@ -81,6 +107,7 @@ class _CPUMode(XMLBuilder):
             if model.model == name:
                 return model
 
+
 class _CPU(XMLBuilder):
     XML_NAME = "cpu"
     modes = XMLChildProperty(_CPUMode)
@@ -91,6 +118,10 @@ class _CPU(XMLBuilder):
                 return mode
 
 
+#################################
+# DomainCapabilities main class #
+#################################
+
 class DomainCapabilities(XMLBuilder):
     @staticmethod
     def build_from_params(conn, emulator, arch, machine, hvtype):