diff --git a/src/diana/diana.py b/src/diana/diana.py
--- a/src/diana/diana.py
+++ b/src/diana/diana.py
@@ -11,6 +11,11 @@ from .drawer.tikz import Tikz
 
 
 def collect_moves(root):
+	"""Walk the primary variation and collect the move coordinates.
+
+	:param Node root: a node serving as a root for the tree traversal
+	:return: sequence of move colors and coordinates (col, row)
+	:rtype: Iterator[("b" or "w", (int, int))]"""
 	node = root
 	while len(node.children) > 0:
 		b = node.get_prop("B")
@@ -55,6 +60,13 @@ W: {PW} {WR}
 		print("done")
 
 	def create_diagram(self, start, end):
+		"""Create and return a diagram drawer instance.
+
+		:param int start: the initial move
+		:param int end: the first omitted move, similar to sequence slices
+		:return: a diagram instance
+		:rtype: Drawer"""
+
 		# initialize the diagram
 		template = Svg()
 
@@ -73,7 +85,7 @@ W: {PW} {WR}
 
 			color, move = self._moves[k]
 			if move == tuple():
-				template.overlays.append((k, "pass"))  # !!
+				template.overlays.append((k, "pass"))
 				continue
 			else:
 				(c, r) = move
@@ -93,6 +105,9 @@ W: {PW} {WR}
 		return {k: self._record.get(k, default) for k in field_names}
 
 	def _set_move(self, k):
+		"""Rewind the internal game state to move k.
+
+		:param int k: the move number"""
 		self._game = go.Go()
 
 		black_stones = self._record.root.get_prop("AB")
@@ -107,13 +122,20 @@ W: {PW} {WR}
 		for i in range(k):
 			(color, move) = self._moves[i]
 			if move == tuple():
-				continue # pass
+				continue  # pass
 			self._move(color, *move)
 
 	def _move(self, color, c, r):
+		"""Make a single move.
+
+		:param str color: "b" or "w"
+		:param int c: column
+		:param int r: row
+		:return: True if we can continue with another move, False on abort"""
 		if not self._game.move(BLACK if color=='b' else WHITE, c, r):
-			# !! we do not honor http://red-bean.com/sgf/ff5/m_vs_ax.htm at the moment
-			msg = "illegal move: {0} at {1},{2}".format(self._game.move_count + 1, c, r)
+			# we do not honor http://red-bean.com/sgf/ff5/m_vs_ax.htm at the moment
+			# we accept and process only legal moves
+			msg = "illegal move: {0} at {1},{2}".format(self._game.move_count+1, c, r)
 			if cfg.keep_broken:
 				print(msg)
 			else: