enhanced Javadoc and REST API doc for target time estimation

java/com.sap.sailing.domain/src/com/sap/sailing/domain/tracking/TrackedRace.java

@@ -774,10 +774,16 @@ public interface TrackedRace extends Serializable {
     boolean isUsingMarkPassingCalculator();
     
     /**
-     * @param timepoint Used for positions of marks and wind information
+     * Calculates the estimated time it takes a competitor to sail the race, from start to finish.
+     * 
+     * @param timepoint
+     *            Used for positions of marks and wind information; note that sometimes the marks are not in place yet
+     *            when the race starts and that a windward mark may be collected already before the race finishes.
+     * 
      * @return estimated time it takes to complete the race
-     * @throws NotEnoughDataHasBeenAddedException thrown if not enough polar data has been added or polar data service
-     * is not available
+     * 
+     * @throws NotEnoughDataHasBeenAddedException
+     *             thrown if not enough polar data has been added or polar data service is not available
      * @throws NoWindException
      */
     Duration getEstimatedTimeToComplete(TimePoint timepoint) throws NotEnoughDataHasBeenAddedException, NoWindException;

java/com.sap.sailing.server.gateway/webservices/api/v1/raceTargetTimeGetDoc.html

@@ -12,7 +12,10 @@
 <h2>URL: /api/v1/regattas/{regattaname}/races/{racename}/targettime</h2>
 
 <b>Description:</b>
-<p>Gets the estimated target time of the race</p>
+<p>Gets the estimated time it will take to sail a race. The mark positions and the wind data are
+taken from the optional timeasmillis parameter which defaults to the current time. Note that sometimes the marks are not in place yet
+when the race starts and that a windward mark may be collected already before the race finishes.
+</p>
 <br/>
 <table>
 	<tr>