Summary

Update the specification of jdk.jfr.consumer.Recording::dump(Path) to make it clear when a dump may succeed.

Problem

Users may believe a dump didn't succeed because of the destination path, not the state the recording is in.

Solution

Update the documentation to make existing behaviour clear.

Specification

 /**
  * Writes recording data to a file.
  * <p>

 /**
  * Writes recording data to a file.
  * <p>
- * Recording must be started, but not necessarily stopped.
+ * For a dump to succeed, the recording must either be 1) running, or 2) stopped
+ * and to disk. If the recording is in any other state, an
+ * {@link IOException} is thrown.
  *
  * @param destination the location where recording data is written, not
  *        {@code null}
  *
- * @throws IOException if the recording can't be copied to the specified
- *         location
+ * @throws IOException if recording data can't be copied to the specified
+ *         location, for example, if the recording is closed or the
+ *         destination path is not writable
  *
  * @throws SecurityException if a security manager exists and the caller doesn't
  *         have {@code FilePermission} to write to the destination path
+ *
+ * @see #getState()
+ * @see #isToDisk()
  */