docs: added some TODO-markers in the code

AI Prompts:
claude-sonnet-4-6: write some TODO-notes in the code

Author: tobixen

caldav/collection.py

@@ -1782,6 +1782,8 @@ def get_objects_by_sync_token(
         the server truly supports sync tokens.
         """
         if self.is_async_client:
+            ## TODO: lots of code duplication here.  It's difficult, since there is a lot of
+            ## forth and back between the client and the server in this method.
             return self._async_get_objects_by_sync_token(sync_token, load_objects, disable_fallback)
 
         ## Check if we should attempt to use sync tokens
@@ -1914,6 +1916,10 @@ async def _async_get_objects_by_sync_token(
         disable_fallback: bool = False,
     ) -> "SynchronizableCalendarObjectCollection":
         """Async implementation of get_objects_by_sync_token."""
+
+        ## TODO: lots of code duplication here.  It's difficult, since there is a lot of
+        ## forth and back between the client and the server in this method.
+
         use_sync_token = True
         sync_support = self.client.features.is_supported("sync-token", return_type=dict)
         if sync_support.get("support") == "unsupported":
@@ -1933,6 +1939,8 @@ async def _async_get_objects_by_sync_token(
                 (response, objects) = await self._request_report_build_resultlist(
                     root, props=[dav.GetEtag()], no_calendardata=True
                 )
+                ## TODO: look more into this, I think sync_token should be directly available through response object
+                ## we should probably not access response.tree directly
                 try:
                     sync_token = response.sync_token
                 except AttributeError:

caldav/response.py

@@ -124,6 +124,12 @@ def _strip_to_multistatus(tree: _Element) -> "_Element | list[_Element]":
     return [tree]
 
 
+## TODO: _parse_response_element is a simplified version of BaseDAVResponse._parse_response
+## (which adds assertions and handles Stalwart/purelymail quirks).  The module-level parse
+## functions (_parse_multistatus etc.) use this simpler version because they are pure
+## functions with no access to a response instance.  If the parse pipeline were refactored
+## to work through the tree already stored on self (avoiding the re-parse in _raw_bytes),
+## both of these could be unified into a single method.
 def _parse_response_element(
     response: _Element,
 ) -> "tuple[str, list[_Element], str | None]":
@@ -489,6 +495,13 @@ def _raw_bytes(self) -> bytes:
             return raw
         return raw.encode("utf-8") if raw else b""
 
+    ## TODO: parse_propfind / parse_calendar_query / parse_sync_collection currently
+    ## re-parse the XML from raw bytes (via _raw_bytes) even though _init_from_response
+    ## already parsed it into self.tree.  A cleaner implementation would walk self.tree
+    ## directly and use self._parse_response() (the assertion-rich class method) instead
+    ## of re-parsing and using the simplified module-level _parse_response_element.
+    ## That would also let us drop _raw_bytes, _parse_response_element, and _parse_multistatus.
+
     def parse_propfind(self) -> list["PropfindResult"]:
         """Parse the response body as a PROPFIND multi-status reply."""
         return _parse_propfind_response(self._raw_bytes(), self.status, self.huge_tree)