docs: various documentation improvements

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socioeconomic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+monora@gmail.com. All complaints will be reviewed and investigated promptly
+and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

.github/CONTRIBUTING.md

@@ -34,7 +34,7 @@ bundle install
 
 ```bash
 bundle exec rake test          # full test suite
-bundle exec rake test TEST=test/stream_test.rb  # single file
+bundle exec rake test TEST=test/teststream.rb   # single file
 ```
 
 ## How to Contribute

README.rdoc

@@ -1,5 +1,5 @@
 {<img src="https://github.com/monora/stream/actions/workflows/ruby.yml/badge.svg" alt="Build Status" />}[https://github.com/monora/stream/actions/workflows/ruby.yml]
-{<img src="https://badge.fury.io/rb/stream.svg" alt="Version" />}[https://badge.fury.io/rb/stream]
+{<img src="https://img.shields.io/gem/v/stream.svg" alt="Version" />}[https://rubygems.org/gems/stream]
 
 = Extended External Iterators (forward and backward)
 
@@ -34,7 +34,7 @@ conditions must be true:
 
  s.at_beginning? <=> s.current_edge == [x0,x1]
  s.at_end? <=> s.current_edge == [xn,xn+1]
- s.isEmpty? <=> s.at_beginning? && s.at_end? <=> s.current_edge == [x0,x1] <=> n = 0
+ s.empty? <=> s.at_beginning? && s.at_end? <=> s.current_edge == [x0,x1] <=> n = 0
  s.set_to_end => s.at_end?
  s.set_to_begin => s.at_beginning?
 

lib/stream.rb

@@ -24,15 +24,17 @@ def at_beginning?
   end
 
   # Move forward one position. Returns the _target_ of current_edge.
-  # Raises Stream::EndOfStreamException if at_end? is true.
+  # @raise [EndOfStreamException] if at_end? is true
+  # @return [Object] the next element
   def forward
     raise EndOfStreamException if at_end?
 
     basic_forward
   end
 
-  # Move backward one position. Returns the _source_ of current_edge. Raises
-  # Stream::EndOfStreamException if at_beginning? is true.
+  # Move backward one position. Returns the _source_ of current_edge.
+  # @raise [EndOfStreamException] if at_beginning? is true
+  # @return [Object] the previous element
   def backward
     raise EndOfStreamException if at_beginning?
 
@@ -79,6 +81,8 @@ def basic_peek
   # This is similar to #detect, but starts the search from the
   # current position. #detect, which is inherited from Enumerable uses
   # #each, which implicitly calls #set_to_begin.
+  # @yield [element] each element in forward direction
+  # @return [Object, nil] the first matching element, or nil
   def move_forward_until
     until at_end?
       element = basic_forward
@@ -89,6 +93,8 @@ def move_forward_until
 
   # Move backward until the boolean block is not false and returns the element
   # found. Returns nil if no object matches.
+  # @yield [element] each element in backward direction
+  # @return [Object, nil] the first matching element, or nil
   def move_backward_until
     until at_beginning?
       element = basic_backward
@@ -192,6 +198,7 @@ class CollectionStream < BasicStream
     attr_reader :pos
 
     # Creates a new CollectionStream for the indexable sequence _seq_.
+    # @param seq [Array] an integer-indexed collection
     def initialize(seq)
       @seq = seq
       set_to_begin
@@ -252,6 +259,7 @@ class IntervalStream < BasicStream
 
     # Create a new IntervalStream with upper bound _stop_. stop - 1 is the last
     # element. By default _stop_ is zero which means that the stream is empty.
+    # @param stop [Integer] exclusive upper bound; stream yields 0..stop-1
     def initialize(stop = 0)
       @stop = stop - 1
       set_to_begin
@@ -617,6 +625,8 @@ class ImplicitStream < BasicStream
     #
     # If a block is given to new, than it is called with the new ImplicitStream
     # stream as parameter letting the client overwriting the default blocks.
+    # @param other_stream [Stream, nil] optional stream to wrap
+    # @yield [self] the new ImplicitStream instance for customization
     def initialize(other_stream = nil)
       # Initialize with defaults
       @at_beginning_proc = proc { true }
@@ -674,7 +684,9 @@ def set_to_begin
 
   ##
   # Return a Stream::FilteredStream which iterates over all my elements
-  # satisfying the condition specified  by the block.
+  # satisfying the condition specified by the block.
+  # @yield [element] filter predicate
+  # @return [FilteredStream]
   def filtered(&block)
     FilteredStream.new(self, &block)
   end
@@ -687,6 +699,8 @@ def reverse
   # Create a Stream::MappedStream wrapper on self. Instead of returning the
   # stream element on each move, the value of calling _mapping_ is returned
   # instead. See Stream::MappedStream for examples.
+  # @yield [element] mapping block applied to each element
+  # @return [MappedStream]
   def collect(&mapping)
     MappedStream.new(self, &mapping)
   end
@@ -708,8 +722,10 @@ def concatenate_collected(&mapping)
     collect(&mapping).concatenate
   end
 
-  # Create a Stream::ConcatenatedStream by concatenatating the receiver and
-  # _other_stream_
+  # Create a Stream::ConcatenatedStream by concatenating the receiver and
+  # _other_stream_.
+  # @param other [Stream] the stream to append
+  # @return [ConcatenatedStream]
   #
   #  (%w(a b c).create_stream + [4,5].create_stream).to_a
   #  ==> ["a", "b", "c", 4, 5]