From 114f8eceabb1649a57a6db85d4d13ad8fe083a3e Mon Sep 17 00:00:00 2001
From: paul-loedige <paul@gve-loedige.de>
Date: Fri, 25 Dec 2020 21:40:25 +0100
Subject: [PATCH] improved documentation

---
 xml_reader.py | 44 ++++++++++++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 16 deletions(-)

diff --git a/xml_reader.py b/xml_reader.py
index 4e741ea..bc79990 100644
--- a/xml_reader.py
+++ b/xml_reader.py
@@ -2,11 +2,15 @@ from lxml import etree
 class Xml_reader:
     """ reader for the XML configuration """
 
-    def __init__(self, xml_path, xsd_path):
+    def __init__(self, xml_path:str, xsd_path:str):
         """inits the reader
 
         Args:
-            path (string): path to the XML config file
+            xml_path (str): the path to the XML file
+            xsd_path (str): the path to the XSD file
+
+        Raises:
+            SyntaxError: validity of XML file is checked with the XSD file
         """
         #check the XML for validity using the XSD file
         if not self.validate(xml_path,xsd_path):
@@ -14,11 +18,11 @@ class Xml_reader:
         self.root = etree.parse(xml_path).getroot()
 
     def validate(self, xml_path:str, xsd_path: str) -> bool:
-        """validates a xml by using a xsd file
+        """validates a XML by using a XSD file
 
         Args:
-            xml_path (str): the path to the xml file
-            xsd_path (str): the path to the xsd file
+            xml_path (str): the path to the XML file
+            xsd_path (str): the path to the XSD file
 
         Returns:
             bool: result of the validation
@@ -26,27 +30,32 @@ class Xml_reader:
         xml_schema = etree.XMLSchema(etree.parse(xsd_path))
         return xml_schema.validate(etree.parse(xml_path))
 
-    def get_device_names(self):
-        """returns the names of all devices in the config
+    def get_device_names(self) -> list:
+        """lists all the device names from the config XML
 
         Returns:
-            list: names of the devices
+            list: all device names as strings
         """
         return [device.get("name") for device in self.root.findall('Device')]
 
-    def get_value_info(self,device_name):
-        """returns the value information for a device
+    def get_value_info(self,device_name:str) -> dict:
+        """returns the value information for a given device
 
         Args:
-            device_name (string): the name of the relevant device
+            device_name (str): the name of a device
 
         Returns:
             dict: {'type','unit','offset','factor'}
+
+        Raises:
+            NameError: device_name will be checked against the config XML
         """
+        #check if a device exists in the config XML
         if self.root.find("Device[@name='%s']" % device_name) is None:
-            return None
+            raise NameError("unknown device %s" % device_name)
         value_info = self.root.find(
             "Device[@name='%s']/ValueInfo" % device_name)
+        #format the output
         return {
             'type': value_info.get('type'),
             'unit': value_info.get('unit'),
@@ -56,17 +65,20 @@ class Xml_reader:
                 else value_info.find("Factor").text,
         } 
     
-    def get_port(self,device_name):
-        """returns the port details for a device
+    def get_port(self,device_name:str) -> dict:
+        """returns the information about a port of a given device
 
         Args:
-            device_name (string): the name of the relevant device
+            device_name (str): the name of a device
 
         Returns:
             dict: {'protocol', [list: pins]}
+
+        Raises:
+            NameError: device_name will be checked against the config XML
         """
         if self.root.find("Device[@name='%s']" % device_name) is None:
-            return None
+            raise NameError("unknown device %s" % device_name)
         port = self.root.find(
             "Device[@name='%s']/Port" % device_name)
         return {