diff --git a/src/go/engine.py b/src/go/engine.py
--- a/src/go/engine.py
+++ b/src/go/engine.py
@@ -7,6 +7,7 @@ from . import core
 #
 # @param colorIn {BLACK,WHITE}: color to start the sequence
 # @param colorOut {BLACK,WHITE}: color to close the sequence
+# @return [(c,row,col), ...] or None. c in {BLACK,WHITE} == {1,-1}
 def getTransitionSequence(state1,state2,colorIn,colorOut,diff):
 	eng.load(state1)
 	return eng.iterativelyDeepen(state2,diff,colorIn,colorOut)
@@ -22,7 +23,9 @@ class SpecGo(core.Go):
 		Deletions and replacements had to be captured, so we add their liberties.
 		Also any non-missing stones of partially deleted (or replaced) groups had to be replayed, so add them too.
 		Needs to handle snapback, throw-in.
-		There's no end to what could be theoretically relevant, but such sequences are long and we will pretend they won't happen."""
+		There's no end to what could be theoretically relevant, but such sequences are long and we will pretend they won't happen.
+
+		:return: (blackMoves,whiteMoves) == ({(row,col), ...}, {(row,col), ...})"""
 		res=({PASS},{PASS})
 		for d in diff:
 			(r,c,action,color)=d
@@ -64,7 +67,9 @@ class Engine:
 		self._g.load(state1)
 
 	def iterativelyDeepen(self,state2,diff,colorIn,colorOut):
-		"""Search for a move sequence from the loaded state to state2. Tries progressively longer sequences."""
+		"""Search for a move sequence from the loaded state to state2. Tries progressively longer sequences.
+
+		:return: [(c,row,col), ...] or None. c in {BLACK,WHITE} == {1,-1}"""
 		self._moveList=self._g.listRelevantMoves(diff)
 		startDepth=1 if colorIn==colorOut else 2
 		self._g.toMove=colorIn