Clarify MoveStream API

[mcognetta]

Clarifies the MoveStream API documentation to describe the structure of the updates and a difference in behavior with some variants.

I also removed one of the messages in the example for this API call, as the initial game state with no move is never sent as an update.

---

Two small notes, will open issues about them unless I am advised against it here:

1) It seems Horde and Racing Kings's game updates start from the current position rather than the starting position. Is this on purpose? Actually I can't tell exactly why this is the case from reading the code, but it seems to only be games that have standardInitialPosition = false (except that Chess960 works as expected).

2) Standard games only show the complete fen at the start and end of games in the updates. However, the complete fen is known at all times. IMO it should be displayed at all times so that the user does not have to manually track the true fen. I believe it just this line needs to be changed to include the castle info:

https://github.com/lichess-org/lila/blob/6067f0c1d61d275925849c5057f0e6aef6bee58e/modules/round/src/main/ApiMoveStream.scala#L94-L106

^ this link preview isn't displaying correctly, so I have reproduced it here:

  private def toJson(
      boardFen: String,
      turnColor: Color,
      lastMoveUci: Option[String],
      clock: Option[(Centis, Centis)]
  ): JsObject =
    clock.foldLeft(
      Json
        .obj("fen" -> s"$boardFen ${turnColor.letter}")
        .add("lm" -> lastMoveUci)
    ) { case (js, clk) =>
      js ++ Json.obj("wc" -> clk._1.roundSeconds, "bc" -> clk._2.roundSeconds)
    }
}

[benediktwerner]

1. seems like a bug. It seems that gameRepo.initialFen returns None for horde and racing kings but Replays.situations interprets that as using the standard starting position which then leads to an invalid move and no moves transmitted. Those behaviors both seem kinda wrong but not sure if anything relies on them?

I also removed one of the messages in the example for this API call, as the initial game state with no move is never sent as an update.

This isn't true. It's always sent as the first "move".

[mcognetta]

This isn't true. It's always sent as the first "move".

I've reverted it. The caller I was using discarded the first update.

seems like a bug. It seems that gameRepo.initialFen returns None for horde and racing kings but Replays.situations interprets that as using the standard starting position which then leads to an invalid move and no moves transmitted. Those behaviors both seem kinda wrong but not sure if anything relies on them?

Yeah, I will file an issue. I don't know enough about the codebase to see if anything relies on it, but it should be brought inline with all the other game types for consistency.