Merge pull request #3139 from danicheg/scaladocs

Tweak some scaladocs

Author: mpilquist

core/shared/src/main/scala/fs2/Pull.scala

@@ -786,8 +786,8 @@ object Pull extends PullLowPriority {
   /** Steps through the stream, providing a `stepLeg`.
     * Yields to head in form of chunk, then id of the scope that was active after step evaluated and tail of the `stream`.
     *
-    * @param stream             Stream to step
-    * @param scopeId            scope has to be changed before this step is evaluated, id of the scope must be supplied
+    * @param stream Stream to step
+    * @param scope  Scope has to be changed before this step is evaluated, id of the scope must be supplied
     */
   private final case class StepLeg[+F[_], +O](stream: Pull[F, O, Unit], scope: Unique.Token)
       extends Action[Nothing, Nothing, Option[Stream.StepLeg[F, O]]]

core/shared/src/main/scala/fs2/Stream.scala

@@ -106,7 +106,7 @@ import Pull.StreamPullOps
   *   - `Stream.emit >=> f == f` (left identity)
   *   - `f >=> Stream.emit === f` (right identity - note weaker equality notion here)
   *   - `(f >=> g) >=> h == f >=> (g >=> h)` (associativity)
-  *  where `Stream.emit(a)` is defined as `chunk(Chunk.singleton(a)) and
+  *  where `Stream.emit(a)` is defined as `chunk(Chunk.singleton(a))` and
   *  `f >=> g` is defined as `a => a flatMap f flatMap g`
   *
   * The monad is the list-style sequencing monad:
@@ -377,7 +377,7 @@ final class Stream[+F[_], +O] private[fs2] (private[fs2] val underlying: Pull[F,
     filterWithPrevious((o1, o2) => eq.neqv(f(o1), f(o2)))
 
   /** Collects all output chunks in to a single chunk and emits it at the end of the
-    * source stream. Note: if more than 2^32-1 elements are collected, this operation
+    * source stream. Note: if more than 2^(32-1)^ elements are collected, this operation
     * will fail.
     *
     * @example {{{
@@ -3827,11 +3827,11 @@ object Stream extends StreamLowPriority {
       override def apply[A](fa: Resource[F, A]): Stream[F, A] = resourceWeak[F, A](fa)
     }
 
-  /** Converts the supplied [[java.lang.Autoclosable]] into a singleton stream. */
+  /** Converts the supplied [[java.lang.AutoCloseable]] into a singleton stream. */
   def fromAutoCloseable[F[_]: Sync, O <: AutoCloseable](fo: F[O]): Stream[F, O] =
     Stream.resource(Resource.fromAutoCloseable(fo))
 
-  /** Like [[fromAutoClosable]] but does not introduce a scope, allowing finalization to occur after
+  /** Like [[fromAutoCloseable]] but does not introduce a scope, allowing finalization to occur after
     * subsequent appends or other scope-preserving transformations.
     *
     * Scopes can be manually introduced via [[Stream#scope]] if desired.
@@ -4035,9 +4035,9 @@ object Stream extends StreamLowPriority {
       * or from the observer pipe (when applied to source chunks) will cause the
       * termination of the resulting stream, and will be raised from this.
       *
-      * @returns A stream that may emit the same outputs as this stream (source),
-      *          in the same order and chunks, and performs the same effects as
-      *          the source; but in which every chunk is processed by the pipe.
+      * @return A stream that may emit the same outputs as this stream (source),
+      *         in the same order and chunks, and performs the same effects as
+      *         the source; but in which every chunk is processed by the pipe.
       */
     def observeAsync(
         maxQueued: Int

core/shared/src/main/scala/fs2/internal/InterruptContext.scala

@@ -29,7 +29,7 @@ import InterruptContext.InterruptionOutcome
 
 /** A context of interruption status. This is shared from the parent that was created as interruptible to all
   * its children. It assures consistent view of the interruption through the stack
-  * @param concurrent   Concurrent, used to create interruption at Eval.
+  * @param deferred Deferred, used to create interruption at Eval.
   *                 If signalled with None, normal interruption is signalled. If signaled with Some(err) failure is signalled.
   * @param ref      When None, scope is not interrupted,
   *                 when Some(None) scope was interrupted, and shall continue with `whenInterrupted`

core/shared/src/main/scala/fs2/internal/Scope.scala

@@ -303,7 +303,7 @@ private[fs2] final class Scope[F[_]] private (
     go(self, Chain.empty)
   }
 
-  /** @returns true if the given `scopeId` identifies an ancestor of this scope, or false otherwise.
+  /** @return true if the given `scopeId` identifies an ancestor of this scope, or false otherwise.
     */
   def descendsFrom(scopeId: Unique.Token): Boolean = findSelfOrAncestor(scopeId).isDefined
 

core/shared/src/main/scala/fs2/internal/ScopedResource.scala

@@ -54,7 +54,7 @@ import fs2.Compiler
   * scope is closed (or when the resource lease is no longer required) release the lease with `Lease#cancel`.
   *
   * Note that every method which may potentially call a resource finalizer returns `F[Either[Throwable, Unit]]`
-  * instead of `F[Unit]`` to make sure any errors that occur when releasing the resource are properly handled.
+  * instead of `F[Unit]` to make sure any errors that occur when releasing the resource are properly handled.
   */
 private[fs2] sealed abstract class ScopedResource[F[_]] {
 

io/jvm-native/src/main/scala/fs2/io/file/DeprecatedFilesApi.scala

@@ -134,7 +134,7 @@ private[file] trait DeprecatedFilesApi[F[_]] { self: Files[F] =>
     * readAttributes method and the file type tested with the BasicFileAttributes.isDirectory() method.
     *
     * @param path the path to the file to test
-    * @param options - options indicating how symbolic links are handled
+    * @param linkOption - options indicating how symbolic links are handled
     * @return true if the file is a directory; false if the file does not exist, is not a directory, or it cannot be determined if the file is a directory or not.
     */
   @deprecated("Use overload which uses fs2.io.file.Path", "3.1.0")
@@ -158,7 +158,7 @@ private[file] trait DeprecatedFilesApi[F[_]] { self: Files[F] =>
     * method and the file type tested with the BasicFileAttributes.isRegularFile() method.
     *
     * @param path the path to the file
-    * @param options options indicating how symbolic links are handled
+    * @param linkOption options indicating how symbolic links are handled
     * @return true if the file is a regular file; false if the file does not exist, is not a regular file, or it cannot be determined if the file is a regular file or not.
     */
   @deprecated("Use isRegularFile which uses fs2.io.file.Path", "3.1.0")

io/shared/src/test/scala/fs2/io/file/FilesExamples.scala

@@ -82,7 +82,7 @@ object Examples {
     *
     * We have two options:
     * - call pathWithGreatestIn using the inverse of the feature, ensuring to "undo" the inverse on the
-    *   result. This requires a `Group` constraint on A`
+    *   result. This requires a `Group` constraint on `A`
     * - pass a different `Order` instance which reverses the order
     *
     * The second option is better for callers and is more general (it doesn't require a `Group[A]` instance).