update docstrings

uds/database/abstract_database.py

@@ -34,20 +34,6 @@ def encode(self,
         :param sid: Service Identifier of a diagnostic message.
         :param data_records_values: Value for each Data Record that is part a service message.
 
-            Each type represent other data:
-
-            - int type - raw value of a Data Record
-            - float type - physical value of a Data Record
-            - str type - text value of a Data Record
-            - iterable type - contains values for children Data Records
-            - dict type - values of children Data Records
-
-            .. warning:: Providing physical value as float might sometime cause issues due
-                `floating-point precision <https://docs.python.org/3/tutorial/floatingpoint.html>`_.
-                The closest raw value would be evaluated and put into a payload.
-
-                To avoid rounding, provide raw value (int type).
-
         :raise TypeError: Provided SID value is neither int, RequestSID nor ResponseSID type.
         :raise ValueError: This database has no implementation for provided SID value.
 

uds/database/data_record/abstract_data_record.py

@@ -5,22 +5,51 @@
 from abc import ABC, abstractmethod
 from typing import Dict, Optional, Sequence, Tuple, TypedDict, Union
 
+
 DataRecordValueAlias = Union[
     int,  # raw value
-    float,  # physical value calculated through formula (the closest raw value would be encoded)
-    str,  # carried text value
+    float,  # physical value calculated through formula
+    str,  # text (physical) value from either Text Table or Text encoding
     Dict[str, "DataRecordValueAlias"],  # value of container's children
-    Sequence[Dict[str, "DataRecordValueAlias"]],  # values for reoccurring container (or its children)
+    Sequence[Union[int, Dict[str, "DataRecordValueAlias"]]],  # values for reoccurring container
 ]
-"""Alias of Data Records' input value."""
+"""
+Alias of Data Records' input value.
+
+Each type represent other data:
+
+- int type - raw value of a data record
+- float type - physical value of a formula data record
+
+    .. warning:: Providing physical value as float might sometime cause issues due
+        `floating-point precision <https://docs.python.org/3/tutorial/floatingpoint.html>`_.
+        The closest raw value would be evaluated and put into a payload.
+
+        To avoid rounding, provide raw value (int type).
 
-DataRecordPhysicalValueAlias =Union[
+- str type - text (physical) value of either text table or text data record
+- dict type - values for children of a container data records
+- sequence type - values for following occurrences of a container data record
+"""
+
+DataRecordPhysicalValueAlias = Union[
     int,  # physical value is the same as raw value
     float,  # physical value calculated through formula
     str,  # decoded text value
     Tuple[Tuple["DecodedDataRecord", ...], ...]  # decoded container value, each element is another record
 ]
-"""Alias of Data Records' physical value."""
+"""
+Alias of Data Records' physical value.
+
+Each type represent other data:
+
+- int type - physical value is the same as raw value
+- float type - value received through formula calculation
+- str type - text value received either through encoding (e.g. ASCII, UTF-8)
+  or mapping (each value has specific meaning)
+- tuple type - one element for each container occurrence; each element is a tuple with values for children data records
+"""
+
 
 class DecodedDataRecord(TypedDict):
     """Structure of decoded Data Record."""
@@ -63,7 +92,7 @@ def max_raw_value(self):
         :return: Maximum value that can be represented by `length` bits.
         """
         return (1 << self.length) - 1
-      
+
     @property  # noqa: F841
     @abstractmethod
     def is_reoccurring(self) -> bool:

uds/database/services/abstract_service.py

@@ -35,57 +35,39 @@ def decode(self, payload: RawBytesAlias) -> List[DecodedDataRecord]:
         """
 
     def encode(self, sid: int, **data_records_values: DataRecordValueAlias) -> RawBytesListAlias:
-        # TODO
+        """
+        Encode diagnostic message payload for this service.
+
+        :param sid: Value of Service Identifier. It should be either equal to either `request_sid` or `response_sid`.
+        :param data_records_values: Value for each data record that is part of a service message.
+
+        :raise ValueError: Provided `sid` value is neither equal to request SID value nor response SID value for this
+            diagnostic service.
+
+        :return: Payload of a diagnostic message.
+        """
         if sid == self.request_sid:
             return self.encode_request(**data_records_values)
         if sid == self.response_sid:
             return self.encode_response(**data_records_values)
-        raise ValueError
+        raise ValueError("Provided SID value is neither request or response SID value for this service.")
 
     @abstractmethod
     def encode_request(self, **data_records_values: DataRecordValueAlias) -> RawBytesListAlias:
         """
-        Encode diagnostic message payload from data records values.
-
-        :param data_records_values: Value for each Data Record that is part a service message.
-
-            Each type represent other data:
+        Encode diagnostic message payload for this service's request message.
 
-            - int type - raw value of a Data Record
-            - float type - physical value of a Data Record
-            - str type - text value of a Data Record
-            - sequence - contains values for children Data Records
-            - dict type - values of children Data Records
+        :param data_records_values: Value for each data record that is part of a service message.
 
-            .. warning:: Providing physical value as float might sometime cause issues due
-                `floating-point precision <https://docs.python.org/3/tutorial/floatingpoint.html>`_.
-                The closest raw value would be evaluated and put into a payload.
-
-                To avoid rounding, provide raw value (int type).
-
-        :return: Payload of a diagnostic message.
+        :return: Payload of a request diagnostic message.
         """
 
     @abstractmethod
     def encode_response(self, **data_records_values: DataRecordValueAlias) -> RawBytesListAlias:
         """
-        Encode diagnostic message payload from data records values.
-
-        :param data_records_values: Value for each Data Record that is part a service message.
+        Encode diagnostic message payload for this service's response message.
 
-            Each type represent other data:
+        :param data_records_values: Value for each data record that is part of a service message.
 
-            - int type - raw value of a Data Record
-            - float type - physical value of a Data Record
-            - str type - text value of a Data Record
-            - sequence - contains values for children Data Records
-            - dict type - values of children Data Records
-
-            .. warning:: Providing physical value as float might sometime cause issues due
-                `floating-point precision <https://docs.python.org/3/tutorial/floatingpoint.html>`_.
-                The closest raw value would be evaluated and put into a payload.
-
-                To avoid rounding, provide raw value (int type).
-
-        :return: Payload of a diagnostic message.
+        :return: Payload of a response diagnostic message.
         """