Stephen Colebourne writes on core-libs-dev:

I recently fell into the trap of misusing the method
Executors.newScheduledThreadPool() despite having read the Javadoc:

    /**
     * Creates a thread pool that can schedule commands to run after a
     * given delay, or to execute periodically.
     * @param corePoolSize the number of threads to keep in the pool,
     * even if they are idle
     * @return a newly created scheduled thread pool
     * @throws IllegalArgumentException if {@code corePoolSize < 0}
     */

The description of `corePoolSize` implies to me a minimum number of
threads for the pool, and as such I expected the pool to grow
according to demand. Unfortunately, it actually acts as a fixed-size
thread pool. `ScheduledThreadPoolExecutor` is also documented subtly
re fixed-size. In both cases, it should be clearly specified that the
service has a fixed number of threads.

See here for others suffering similar confusion:
https://stackoverflow.com/questions/34273365/what-does-it-means-corepoolsize-param-of-newscheduledthreadpool-method

Could I request the Javadoc to be clarified?

Is there a case for a `ScheduledExecutorService` implementation whose
threads expand based on demand?