docs(sdk): improve documentation for Games

Author: xeruf

sdk/src/server-api/sc/api/plugins/TwoPlayerGameState.kt

@@ -10,34 +10,34 @@ abstract class TwoPlayerGameState<P : Player>(
     abstract val first: P
     abstract val second: P
     abstract val board: IBoard
-
-    /** List of all teams. */
+    
+    /** Der Spieler, der das Spiel begonnen hat. */
+    val startPlayer: P
+        get() = getPlayer(startTeam)
+    
+    /** Liste aller Spieler in Reihenfolge. */
     val players: List<P>
         get() = listOf(first, second)
 
-    /** Die Namen der beiden Spieler. */
+    /** @returns die Namen aller Spieler in Reihenfolge. */
     val playerNames: Array<String>
         get() = arrayOf(first.displayName, second.displayName)
 
-    /** The Team active in the current turn. */
+    /** @return das Team, das dran ist. */
     abstract val currentTeam: ITeam
-
-    /** The Player whose team's turn it is. */
+    
+    /** @return das Team, das nicht dran ist. */
+    val otherTeam: ITeam
+        get() = currentTeam.opponent()
+    
+    /** Der Spieler, der am Zug ist. */
     open val currentPlayer: P
         get() = getPlayer(currentTeam)
 
-    /** The player opposite to the currently active one. */
+    /** Der Spieler, der nicht am Zug ist. */
     val otherPlayer: P
         get() = getPlayer(otherTeam)
 
-    /** The Team opposite to the currently active one. */
-    val otherTeam: ITeam
-        get() = currentTeam.opponent()
-
-    /** Der Spieler, der das Spiel begonnen hat. */
-    val startPlayer: P
-        get() = getPlayer(startTeam)
-
     /** Letzter getaetigter Zug. */
     abstract val lastMove: IMove?
 

sdk/src/server-api/sc/framework/plugins/AbstractGame.kt

@@ -37,7 +37,8 @@ abstract class AbstractGame<P : Player>(override val pluginUUID: String) : IGame
      * @param fromPlayer The player who invoked this action.
      * @param data       The plugin-specific data.
      *
-     * @throws GameLogicException if any invalid action is done, i.e. game rule violation
+     * @throws GameLogicException if no move has been requested from the given [Player]
+     * @throws InvalidMoveException when the given Move is not possible
      */
     @Throws(GameLogicException::class, InvalidMoveException::class)
     override fun onAction(fromPlayer: Player, data: ProtocolMessage) {
@@ -61,11 +62,13 @@ abstract class AbstractGame<P : Player>(override val pluginUUID: String) : IGame
     abstract fun onRoundBasedAction(fromPlayer: Player, data: ProtocolMessage)
 
     /**
-     * Checks if a win condition in the current game state is met.
-     * Checks round limit and end of round (and playerStats).
-     * Checks if goal is reached.
+     * Returns a WinCondition if the Game is over.
+     * Checks:
+     * - if a win condition in the current game state is met
+     * - round limit and end of round (and playerStats)
+     * - whether goal is reached
      *
-     * @return WinCondition with winner and reason or null, if no win condition is yet met.
+     * @return WinCondition, or null if no win condition is met yet.
      */
     abstract fun checkWinCondition(): WinCondition?