Skip to content

Commit

Permalink
Javadoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@garydgregory
garydgregory committed Sep 22, 2024
1 parent ccaae51 commit 4768e90
Showing 1 changed file with 35 additions and 36 deletions.
71 changes: 35 additions & 36 deletions src/main/java/org/apache/commons/lang3/time/StopWatch.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,23 +151,23 @@ boolean isSuspended() {
};

/**
* Tests whether the StopWatch is started. A suspended StopWatch is also started.
* Tests whether this StopWatch is started. A suspended StopWatch is also started.
*
* @return boolean If the StopWatch is started.
* @return boolean If this StopWatch is started.
*/
abstract boolean isStarted();

/**
* Tests whether the StopWatch is stopped. A StopWatch which is not yet started and explicitly stopped is considered stopped.
* Tests whether this StopWatch is stopped. A StopWatch which is not yet started and explicitly stopped is considered stopped.
*
* @return boolean If the StopWatch is stopped.
* @return boolean If this StopWatch is stopped.
*/
abstract boolean isStopped();

/**
* Tests whether the StopWatch is suspended.
* Tests whether this StopWatch is suspended.
*
* @return boolean If the StopWatch is suspended.
* @return boolean If this StopWatch is suspended.
*/
abstract boolean isSuspended();
}
Expand Down Expand Up @@ -206,12 +206,12 @@ public static StopWatch createStarted() {
private final String message;

/**
* The current running state of the StopWatch.
* The current running state of this StopWatch.
*/
private State runningState = State.UNSTARTED;

/**
* Whether the StopWatch has a split time recorded.
* Whether this StopWatch has a split time recorded.
*/
private SplitState splitState = SplitState.UNSPLIT;

Expand All @@ -228,7 +228,7 @@ public static StopWatch createStarted() {
* nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.
* </p>
* <p>
* On Java 8, Instant has millisecond precision, only later versions use nanoseconds.
* On Java 8, Instant has millisecond precision, later versions use nanoseconds.
* </p>
*/
private Instant startInstant;
Expand All @@ -239,7 +239,7 @@ public static StopWatch createStarted() {
* nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.
* </p>
* <p>
* On Java 8, Instant has millisecond precision, only later versions use nanoseconds.
* On Java 8, Instant has millisecond precision, later versions use nanoseconds.
* </p>
*/
private Instant stopInstant;
Expand Down Expand Up @@ -306,7 +306,7 @@ public <T> T get(final Supplier<T> supplier) {
}

/**
* Gets the Duration on the StopWatch.
* Gets the Duration on this StopWatch.
*
* <p>
* This is either the Duration between the start and the moment this method is called, or the Duration between start and stop.
Expand Down Expand Up @@ -356,15 +356,15 @@ public long getNanoTime() {
}

/**
* Gets the split Duration on the StopWatch.
* Gets the split Duration on this StopWatch.
*
* <p>
* This is the Duration between start and latest split.
* </p>
*
* @return the split Duration
*
* @throws IllegalStateException if the StopWatch has not yet been split.
* @throws IllegalStateException if this StopWatch has not yet been split.
* @since 3.16.0
*/
public Duration getSplitDuration() {
Expand All @@ -380,7 +380,7 @@ public Duration getSplitDuration() {
*
* @return the split time in nanoseconds
*
* @throws IllegalStateException if the StopWatch has not yet been split.
* @throws IllegalStateException if this StopWatch has not yet been split.
* @since 3.0
*/
public long getSplitNanoTime() {
Expand All @@ -391,15 +391,15 @@ public long getSplitNanoTime() {
}

/**
* Gets the split time on the StopWatch.
* Gets the split time on this StopWatch.
*
* <p>
* This is the time between start and latest split.
* </p>
*
* @return the split time in milliseconds
*
* @throws IllegalStateException if the StopWatch has not yet been split.
* @throws IllegalStateException if this StopWatch has not yet been split.
* @since 2.1
* @deprecated Use {@link #getSplitDuration()}.
*/
Expand Down Expand Up @@ -484,7 +484,7 @@ public <T, E extends Throwable> T getT(final FailableSupplier<T, E> supplier) th
}

/**
* Gets the time on the StopWatch.
* Gets the time on this StopWatch.
*
* <p>
* This is either the time between the start and the moment this method is called, or the amount of time between start and stop.
Expand All @@ -503,8 +503,8 @@ public long getTime() {
*
* <p>
* This is either the time between the start and the moment this method is called, or the amount of time between start and stop. The resulting time will be
* expressed in the desired TimeUnit with any remainder rounded down. For example, if the specified unit is {@code TimeUnit.HOURS} and the StopWatch time is
* 59 minutes, then the result returned will be {@code 0}.
* expressed in the desired TimeUnit with any remainder rounded down. For example, if the specified unit is {@code TimeUnit.HOURS} and this StopWatch time
* is 59 minutes, then the result returned will be {@code 0}.
* </p>
*
* @param timeUnit the unit of time, not null
Expand All @@ -516,29 +516,29 @@ public long getTime(final TimeUnit timeUnit) {
}

/**
* Tests whether the StopWatch is started. A suspended StopWatch is also started watch.
* Tests whether this StopWatch is started. A suspended StopWatch is also started watch.
*
* @return boolean If the StopWatch is started.
* @return boolean If this StopWatch is started.
* @since 3.2
*/
public boolean isStarted() {
return runningState.isStarted();
}

/**
* Tests whether StopWatch is stopped. The StopWatch which's not yet started and explicitly stopped StopWatch is considered as stopped.
* Tests whether StopWatch is stopped. this StopWatch which's not yet started and explicitly stopped StopWatch is considered as stopped.
*
* @return boolean If the StopWatch is stopped.
* @return boolean If this StopWatch is stopped.
* @since 3.2
*/
public boolean isStopped() {
return runningState.isStopped();
}

/**
* Tests whether the StopWatch is suspended.
* Tests whether this StopWatch is suspended.
*
* @return boolean If the StopWatch is suspended.
* @return boolean If this StopWatch is suspended.
* @since 3.2
*/
public boolean isSuspended() {
Expand All @@ -556,7 +556,7 @@ private long nanosToMillis(final long nanos) {
}

/**
* Resets the StopWatch. Stops it if need be.
* Resets this StopWatch. Stops it if need be.
*
* <p>
* This method clears the internal values to allow the object to be reused.
Expand All @@ -568,13 +568,13 @@ public void reset() {
}

/**
* Resumes the StopWatch after a suspend.
* Resumes this StopWatch after a suspend.
*
* <p>
* This method resumes the watch after it was suspended. The watch will not include time between the suspend and resume calls in the total time.
* </p>
*
* @throws IllegalStateException if the StopWatch has not been suspended.
* @throws IllegalStateException if this StopWatch has not been suspended.
*/
public void resume() {
if (runningState != State.SUSPENDED) {
Expand Down Expand Up @@ -624,7 +624,7 @@ public <E extends Throwable> void runT(final FailableRunnable<E> runnable) throw
* timing from the original start point.
* </p>
*
* @throws IllegalStateException if the StopWatch is not running.
* @throws IllegalStateException if this StopWatch is not running.
*/
public void split() {
if (runningState != State.RUNNING) {
Expand All @@ -641,7 +641,7 @@ public void split() {
* This method starts a new timing session, clearing any previous values.
* </p>
*
* @throws IllegalStateException if the StopWatch is already running.
* @throws IllegalStateException if this StopWatch is already running.
*/
public void start() {
if (runningState == State.STOPPED) {
Expand Down Expand Up @@ -673,7 +673,7 @@ private void startResume() {
* This method ends a new timing session, allowing the time to be retrieved.
* </p>
*
* @throws IllegalStateException if the StopWatch is not running.
* @throws IllegalStateException if this StopWatch is not running.
*/
public void stop() {
if (runningState != State.RUNNING && runningState != State.SUSPENDED) {
Expand All @@ -693,7 +693,7 @@ public void stop() {
* This method suspends the watch until it is resumed. The watch will not include time between the suspend and resume calls in the total time.
* </p>
*
* @throws IllegalStateException if the StopWatch is not currently running.
* @throws IllegalStateException if this StopWatch is not currently running.
*/
public void suspend() {
if (runningState != State.RUNNING) {
Expand All @@ -705,7 +705,7 @@ public void suspend() {
}

/**
* Gets a summary of the split time that the StopWatch recorded as a string.
* Gets a summary of the split time that this StopWatch recorded as a string.
*
* <p>
* The format used is ISO 8601-like, [<i>message</i> ]<i>hours</i>:<i>minutes</i>:<i>seconds</i>.<i>milliseconds</i>.
Expand All @@ -722,7 +722,7 @@ public String toSplitString() {
}

/**
* Gets a summary of the time that the StopWatch recorded as a string.
* Gets a summary of the time that this StopWatch recorded as a string.
*
* <p>
* The format used is ISO 8601-like, [<i>message</i> ]<i>hours</i>:<i>minutes</i>:<i>seconds</i>.<i>milliseconds</i>.
Expand All @@ -745,7 +745,7 @@ public String toString() {
* This method clears the stop time. The start time is unaffected, enabling timing from the original start point to continue.
* </p>
*
* @throws IllegalStateException if the StopWatch has not been split.
* @throws IllegalStateException if this StopWatch has not been split.
*/
public void unsplit() {
if (splitState != SplitState.SPLIT) {
Expand All @@ -754,5 +754,4 @@ public void unsplit() {
splitState = SplitState.UNSPLIT;
}


}

0 comments on commit 4768e90

Please sign in to comment.