py: fix some changelog variable names and documentation

src/api/objects/changelog.py

@@ -36,7 +36,7 @@ EntryTypeGeneric = TypeVar("EntryTypeGeneric", bound=ChangelogEntry)
 # noinspection PyUnresolvedReferences
 class ChangelogEntrySubject(Generic[EntryTypeGeneric], ABC):
     """
-    The subject for a :class:`ChangelogEntry`. An subject is bound to a specific object class and represents 'something'
+    The subject for a :class:`ChangelogEntry`. A subject is bound to a specific object class and represents 'something'
     that can be 'modified'.
     For example, ObjectField is an entry subject since it represents a single value which can be modified. All such
     entries are of type ModificationEntry.
@@ -226,12 +226,6 @@ class ChangelogVersionManager:
 class ChangelogVersionBuilder:
     """
     Used to build a :class:`ChangelogVersionManager`
-    
-    Versions are build in reverse! That is, you start with start_major_version(3) and add mappings for that version.
-    Then you start_minor_version(2) and apply all differences this version has to the next version (v3) (When you start
-    a minor version, all mappings of the next version (the previous build version) are still there). Then
-    start_minor_version(1), etc. For the next major version, you do start_major_version(6), then start_minor_version(5),
-    etc.
     """
     
     def __init__(self):
@@ -283,6 +277,11 @@ class ChangelogVersionBuilder:
         self._current_subject_id_by_subject = {}
     
     def start_version(self, id: int, depends_on: int or None = None):
+        """
+        :param id: ID for this version. Must not be negative
+        :param depends_on: ID of an already finished version on which this version depends. All entries from that
+                           version are copied for the new version, and changes can then be made.
+        """
         if self._current_version != -1:
             raise RuntimeError("Already building a version. Finish previous version with finish_version()")
         if id < 0:

src/api/objects/changelog_v1.py

@@ -120,14 +120,14 @@ class _LegacyModificationEntryCodec(ChangelogEntryCodec[ObjectField]):
     def decode_entry(self,
                      subject: ObjectField,
                      object_id: int,
-                     param2: str or None,  # old value
-                     param3: str) -> ModificationEntry:  # new value
+                     param1: str or None,  # old value
+                     param2: str) -> ModificationEntry:  # new value
         return ModificationEntry(
             subject,
             object_id,
-            None if param2 is None else self._decoder(param2),
-            self._decoder(param3),
-            param2 is None  # It's likely at creation if old value is None, but we can't be sure
+            None if param1 is None else self._decoder(param1),
+            self._decoder(param2),
+            param1 is None  # It's likely at creation if old value is None, but we can't be sure
         )
     
     def supports_encoding(self) -> bool:
@@ -144,12 +144,12 @@ class _DeletionEntryCodec(ChangelogEntryCodec[SimpleChangelogEntrySubject]):
     def decode_entry(self,
                      subject: SimpleChangelogEntrySubject,
                      object_id: int,
-                     param2: str or None,
-                     param3: str) -> DeletionEntry:
+                     param1: str or None,
+                     param2: str) -> DeletionEntry:
         return DeletionEntry(
             subject,
             object_id,
-            _decode_legacy_boolean(param3)
+            _decode_legacy_boolean(param2)
         )
     
     def supports_encoding(self) -> bool:

src/api/objects/current_changelog.py

@@ -131,22 +131,22 @@ class ChangelogUpdate:
             try:
                 if not _VERSION_MANAGER.can_encode_for(entry.subject, version):
                     raise ChangelogEntryError()
-                param1, param2, param3 = _VERSION_MANAGER.encode_entry(version, entry)
+                object_id, param1, param2 = _VERSION_MANAGER.encode_entry(version, entry)
             except ChangelogEntryError:
                 version = _VERSION_MANAGER.get_current_version_id()
                 if not _VERSION_MANAGER.can_encode_for(entry.subject, version):
                     raise RuntimeError("Cannot encode entry for current version")
-                param1, param2, param3 = _VERSION_MANAGER.encode_entry(version, entry)
+                object_id, param1, param2 = _VERSION_MANAGER.encode_entry(version, entry)
             
             id = _VERSION_MANAGER.get_subject_id(entry.subject, version)
             table, field = id
             log_list.append((
                 version,
                 table,
-                param1,
+                object_id,
                 field,
-                param2,
-                param3
+                param1,
+                param2
             ))
         
         transaction.queue_statement(f"""