chilldkg: add API docs for blaming functions

Author: jonasnick

README.md

@@ -927,7 +927,32 @@ recovery data to this participant.
 def participant_blame(blame_state: ParticipantBlameState, cblame: CoordinatorBlameMsg) -> NoReturn
 ```
 
-Perform a participant's blame step of a ChillDKG session. TODO
+Perform a blame investigation (TODO) for a participant in a ChillDKG session.
+
+This function is called when `participant_step2` raises
+`UnknownFaultyParticipantOrCoordinatorError` and allows to further narrow
+down the suspected faulty parties.  It helps narrow down the suspected
+faulty parties by analyzing the blame message provided by the coordinator.
+
+The function does not return a value. Instead, it raises one of two
+exceptions.
+
+*Arguments*:
+
+- `blame_state` - The participant's blame state as contained in
+  UnknownFaultyParticipantOrCoordinatorError thrown by
+  `participant_step2`.
+- `cblame` - The coordinator blame message for this participant as output by
+  `coordinator_blame`.
+
+
+*Raises*:
+
+- `FaultyParticipantOrCoordinatorError` - If another known participant or the
+  coordinator is faulty. See the documentation of the exception for
+  further details.
+- `FaultyCoordinatorError` - If the coordinator is faulty. See the
+  documentation of the exception for further details.
 
 #### coordinator\_step1
 
@@ -1010,7 +1035,17 @@ other participants via a communication channel beside the coordinator.
 def coordinator_blame(pmsgs: List[ParticipantMsg1]) -> List[CoordinatorBlameMsg]
 ```
 
-Perform the coordinator's blame step of a ChillDKG session. TODO
+Generate blame messages for participants to allow blame investigation.
+
+*Arguments*:
+
+- `pmsgs` - List of first messages received from the participants.
+
+
+*Returns*:
+
+- `List[CoordinatorBlameMsg]` - A list of blame messages, each intended for a
+  single participant.
 
 #### recover
 

python/chilldkg_ref/chilldkg.py

@@ -604,7 +604,29 @@ def participant_blame(
     blame_state: ParticipantBlameState,
     cblame: CoordinatorBlameMsg,
 ) -> NoReturn:
-    """Perform a participant's blame step of a ChillDKG session. TODO"""
+    """Perform a blame investigation (TODO) for a participant in a ChillDKG session.
+
+    This function can optionally be called when `participant_step2` raises
+    `UnknownFaultyParticipantOrCoordinatorError`. It narrows down the suspected
+    faulty parties by analyzing the blame message provided by the coordinator.
+
+    This function does not return normally. Instead, it raises one of two
+    exceptions.
+
+    Arguments:
+        blame_state: The participant's blame state as contained in
+            `UnknownFaultyParticipantOrCoordinatorError` raised by
+            `participant_step2`.
+        cblame: The coordinator blame message for this participant as output by
+            `coordinator_blame`.
+
+    Raises:
+        FaultyParticipantOrCoordinatorError: If another known participant or the
+            coordinator is faulty. See the documentation of the exception for
+            further details.
+        FaultyCoordinatorError: If the coordinator is faulty. See the
+            documentation of the exception for further details.
+    """
     encpedpop.participant_blame(
         blame_state=blame_state.enc_blame_state,
         cblame=cblame.enc_cblame,
@@ -709,7 +731,15 @@ def coordinator_finalize(
 
 
 def coordinator_blame(pmsgs: List[ParticipantMsg1]) -> List[CoordinatorBlameMsg]:
-    """Perform the coordinator's blame step of a ChillDKG session. TODO"""
+    """Generate blame messages for participants to allow blame investigation.
+
+    Arguments:
+        pmsgs: List of first messages received from the participants.
+
+    Returns:
+        List[CoordinatorBlameMsg]: A list of blame messages, each intended for a
+            single participant.
+    """
     enc_cblames = encpedpop.coordinator_blame([pmsg.enc_pmsg for pmsg in pmsgs])
     return [CoordinatorBlameMsg(enc_cblame) for enc_cblame in enc_cblames]