Add some function documentation

examples/example_clock.py

@@ -11,6 +11,8 @@
 
 
 def led_callback(comp):
+    """Callback function for LED component change"""
+
     led_port = comp.ports[0]
     time_ns = comp.circuit.time_ns
     name = comp.name()

examples/example_sr.py

@@ -11,6 +11,8 @@
 
 
 def led_callback(comp):
+    """Callback function for LED component change"""
+
     led_port = comp.ports[0]
     time_ns = comp.circuit.time_ns
     name = comp.name()

examples/load_save/example_load_circuit.py

@@ -12,6 +12,7 @@
 
 
 def led_callback(comp):
+    """Callback function for LED component change"""
     led_port = comp.ports[0]
     time_ns = comp.circuit.time_ns
     name = comp.name()

examples/load_save/example_save_circuit.py

@@ -12,6 +12,8 @@
 
 
 def led_callback(comp):
+    """Callback function for LED component change"""
+
     led_port = comp.ports[0]
     time_ns = comp.circuit.time_ns
     name = comp.name()

pyproject.toml

@@ -22,7 +22,6 @@ sections = [
 [tool.pylint.'MESSAGES CONTROL']
 max-line-length = 99
 disable = """
-    missing-function-docstring,
     no-member,
     invalid-name,
     duplicate-code,

src/digsim/circuit/_waves_writer.py

@@ -21,6 +21,7 @@ def __init__(self, filename):
         self._vcd_dict = {}
 
     def init(self, port_info):
+        """Initialize vcd writer"""
         if self._vcd_file is not None or self._vcd_writer is not None:
             self.close()
         self._vcd_file = open(self._vcd_name, mode="w", encoding="utf-8")
@@ -30,6 +31,7 @@ def init(self, port_info):
             self._vcd_dict[f"{port_path}.{port_name}"] = var
 
     def write(self, port, time_ns):
+        """Write port value to vcd file"""
         var = self._vcd_dict.get(f"{port.path()}.{port.name()}")
         if var is None:
             return
@@ -38,6 +40,7 @@ def write(self, port, time_ns):
             self.write(wire, time_ns)
 
     def close(self):
+        """Close vcd file"""
         if self._vcd_writer is not None:
             self._vcd_writer.close()
             self._vcd_writer = None

src/digsim/circuit/components/_button.py

@@ -21,12 +21,14 @@ def init(self):
         self.release()
 
     def push(self):
+        """Push pushbutton"""
         if self._inverted:
             self.O.value = 0
         else:
             self.O.value = 1
 
     def release(self):
+        """Release pushbutton"""
         if self._inverted:
             self.O.value = 1
         else:

src/digsim/circuit/components/_clock.py

@@ -29,6 +29,7 @@ def update(self):
         super().update()
 
     def set_frequency(self, frequency):
+        """Set the clock frequency in hertz"""
         self._frequency = frequency
         half_period_ns = int(1000000000 / (frequency * 2))
         self._portout.set_delay_ns(half_period_ns)
@@ -37,15 +38,12 @@ def set_frequency(self, frequency):
     def active(self):
         return self._portout.value == 1
 
-    @property
-    def wire(self):
-        return self._portout.wire
-
     @wire.setter
     def wire(self, port):
         self._portout.wire = port
 
     def setup(self, frequency=None):
+        """Setup from settings"""
         if frequency is not None:
             self.set_frequency(frequency)
 

src/digsim/circuit/components/_hexdigit.py

@@ -37,17 +37,21 @@ def __init__(self, circuit, name="HexDigit", digits=1, dot=True):
             self.add_port(PortIn(self, "dot"))
 
     def set_digits(self, digits):
+        """Set the number of digits"""
         self._digits = digits
         self.val.width = digits * 4
         self.dot.width = digits
 
     def get_digits(self):
+        """Get the number of digits"""
         return self._digits
 
     def value(self):
+        """Get value"""
         return self.val.value
 
     def dot_active(self, digit_id=1):
+        """Is the dot active for the selected digit_id?"""
         if not self._dot:
             return False
         if self.dot.value == "X":
@@ -56,6 +60,7 @@ def dot_active(self, digit_id=1):
         return dot_value == 1
 
     def segments(self, digit_id=0):
+        """Whch segments are active for the selected digit_id?"""
         if self.value() == "X":
             segments = ""
         else:
@@ -66,6 +71,7 @@ def segments(self, digit_id=0):
         return segments
 
     def setup(self, digits=1):
+        """Setup from settings"""
         if digits is not None:
             self.set_digits(digits)
 

src/digsim/circuit/components/_on_off_switch.py

@@ -28,14 +28,17 @@ def init(self):
         self._set(self._start_on)
 
     def turn_on(self):
+        """Turn on the switch"""
         self.O.value = 1
         self._on = True
 
     def turn_off(self):
+        """Turn off the switch"""
         self.O.value = 0
         self._on = False
 
     def toggle(self):
+        """Toggle the switch"""
         self._set(not self._on)
 
     def onpress(self):

src/digsim/circuit/components/_power.py

@@ -17,10 +17,6 @@ def init(self):
         super().init()
         self.O.value = 1
 
-    @property
-    def wire(self):
-        return self.o.wire
-
     @wire.setter
     def wire(self, port):
         self.O.wire = port
@@ -37,10 +33,6 @@ def init(self):
         super().init()
         self.O.value = 0
 
-    @property
-    def wire(self):
-        return self.o.wire
-
     @wire.setter
     def wire(self, port):
         self.O.wire = port

src/digsim/circuit/components/_seven_segment.py

@@ -16,6 +16,7 @@ def __init__(self, circuit, name="SevemSegment"):
             self.add_port(PortIn(self, portname))
 
     def segments(self):
+        """Get the active segments"""
         segments = ""
         for portname in self.PORTLIST:
             if self.port(portname).value == 1:

src/digsim/circuit/components/_yosys_atoms.py

@@ -12,6 +12,12 @@
 
 class ClassNameParameterComponent(Component):
     def name_to_level(self, index):
+        """
+        Helper function to convert a specific position in the class name
+        to a logic level:
+        N/0 ==> 0
+        P/1 ==> 1
+        """
         class_name = self.__class__.__name__
         split = class_name.split("_")
         level = split[2][index]

src/digsim/circuit/components/_yosys_component.py

@@ -65,6 +65,7 @@ def _setup_base(self):
         self._add_port("1", static_levels.high, driver=True)
 
     def load(self, filename):
+        """Load yosys json netlist file"""
         self._filename = filename
         with open(self._filename, encoding="utf-8") as json_file:
             self._json = json.load(json_file)
@@ -168,6 +169,7 @@ def _add_netnames(self):
             self._add_netname(netname, netname_dict)
 
     def setup(self, path=None):
+        """Setup from settings"""
         if path is not None:
             path = self.circuit.load_path(path)
             self.load(path)

src/digsim/circuit/components/atoms/_component.py

@@ -27,20 +27,27 @@ def __init__(self, circuit, name="", display_name=None):
         self._display_name = display_name or self.__class__.__name__
 
     def init(self):
+        """Initialize port, will be called when circuit is initialized"""
         for port in self._ports:
             port.init()
 
     def add_port(self, port):
+        """
+        Add port to component,
+        also add a 'portname' variable to the component with help of the 'self.__dict__'
+        """
         self.__dict__[port.name()] = port
         self._ports.append(port)
 
     def path(self):
+        """Get component path"""
         if self._parent is not None:
             return f"{self._parent.path()}.{self.name()}"
         return f"{self.name()}"
 
     @property
     def ports(self):
+        """Get component ports"""
         return self._ports
 
     def _get_ports(self, output):
@@ -51,48 +58,72 @@ def _get_ports(self, output):
         return sel_ports
 
     def inports(self):
+        """Get component input ports"""
         return self._get_ports(False)
 
     def outports(self):
+        """Get component output ports"""
         return self._get_ports(True)
 
     def port(self, portname):
+        """Get port with name 'portname'"""
         for port in self._ports:
             if port.name() == portname:
                 return port
         raise ComponentException(f"Port {self.name}:{portname} not found")
 
     @property
     def circuit(self):
+        """Get the circuit for the current component"""
         return self._circuit
 
     def name(self):
+        """Get the component name"""
         return self._name
 
     def set_name(self, name):
+        """Set the component name"""
         self._name = name
 
     def display_name(self):
+        """Get the component display name"""
         return self._display_name
 
     def set_display_name(self, display_name):
+        """Set the component display name"""
         self._display_name = display_name
 
     @property
     def parent(self):
+        """Get parent component"""
         return self._parent
 
     def is_toplevel(self):
+        """Return True if this component is a toplevel component"""
         return self._parent is None
 
     @parent.setter
     def parent(self, parent):
+        """Set component parent"""
         self._parent = parent
 
+    @property
+    def wire(self):
+        """Property needed to be able to have a setter"""
+        raise ComponentException(f"Cannot get wire for component '{self.display_name}'")
+
+    @wire.setter
+    def wire(self, port):
+        """Some components have a single output port, they can implement a wire function"""
+        raise ComponentException(
+            f"'wire' not implemented for this component '{self.display_name}'"
+        )
+
     def update(self):
-        pass
+        """This function is called if a port change and that port should update its parent"""
 
     def remove_connections(self):
+        """Remove component connections"""
         for src_port in self.outports():
             for dst_port in src_port.get_wires():
                 dst_port.set_driver(None)
@@ -102,6 +133,7 @@ def remove_connections(self):
                 dst_port.driver.disconnect(dst_port)
 
     def add_event(self, port, value, delay_ns):
+        """Add delta cycle event"""
         self.circuit.add_event(port, value, delay_ns)
 
     def __str__(self):
@@ -113,6 +145,7 @@ def __str__(self):
         return comp_str
 
     def to_dict(self):
+        """Return the component information as a dict, used when storing a circuit"""
         component_dict = {
             "name": self.name(),
             "display_name": self.display_name(),
@@ -130,6 +163,7 @@ def to_dict(self):
 
     @classmethod
     def from_dict(cls, circuit, json_component):
+        """Factory: Create a component from a dict"""
         component_name = json_component["name"]
         component_type = json_component["type"]
         display_name = json_component.get("display_name")
@@ -148,22 +182,26 @@ def from_dict(cls, circuit, json_component):
 
     @property
     def has_action(self):
+        """Return True if this component is interactive"""
         return False
 
     @property
     def active(self):
+        """Return True if this component is active/activated ('on' for a switch for example)"""
         return False
 
     def onpress(self):
-        pass
+        """What to happen for an interactive activation"""
 
     def onrelease(self):
-        pass
+        """What to happen for an interactive de-activation"""
 
     def settings_from_dict(self, settings):
+        """Get component settings from dict"""
         raise ComponentException(f"No setup for component '{self.display_name}'")
 
     def settings_to_dict(self):
+        """Return component settings as a dict"""
         return {}
 
 
@@ -175,6 +213,7 @@ def __init__(self, circuit, name):
         self._components = []
 
     def add(self, component):
+        """Add sub-component to MultiComponent"""
         self._components.append(component)
         component.parent = self
 
@@ -191,8 +230,10 @@ def __init__(self, circuit, name, callback=None):
         self._callback = callback
 
     def set_callback(self, callback):
+        """Set CallbackComponent callback function"""
         self._callback = callback
 
     def update(self):
+        """Call CallbackComponent callback function if available"""
         if self._callback is not None:
             self._callback(self)