[PATCH 0/6] more minor doc updates

[PATCH 0/6] more minor doc updates

[Eric Wong]

Eric Wong (6):
      update documentation for contributions, remove private address
      doc: minor updates to describe classes, better
      response: remove unnecessary constant alias
      response: more documentation cleanups
      favor require_relative to speed up loading
      response: remove Ruby 1.8-compatibility check

 .document            |  1 +
 .olddoc.yml          |  1 -
 HACKING              | 37 +++++++++++++++++++++++++++++++++++++
 README               | 11 ++++++-----
 ext/kcar/kcar.rl     |  5 +++++
 kcar.gemspec         |  2 +-
 lib/kcar.rb          |  4 ++--
 lib/kcar/response.rb | 21 ++++++++++-----------
 8 files changed, 62 insertions(+), 20 deletions(-)

[PATCH 1/6] update documentation for contributions, remove private address

[Eric Wong]

Add a HACKING doc for potential contributors.

All work for this project has always been public, so lets not
hold ourselves accountable for protecting others' anonymity or
privacy.  Instead, allow and encourage anonymity tools to be
used.
---
 .document    |  1 +
 .olddoc.yml  |  1 -
 HACKING      | 37 +++++++++++++++++++++++++++++++++++++
 README       | 11 ++++++-----
 kcar.gemspec |  2 +-
 5 files changed, 45 insertions(+), 7 deletions(-)
 create mode 100644 HACKING

diff --git a/.document b/.document
index be86662..6d4a537 100644
--- a/.document
+++ b/.document
@@ -1,5 +1,6 @@
 LICENSE
 README
 NEWS
+HACKING
 lib
 ext/kcar/kcar.c
diff --git a/.olddoc.yml b/.olddoc.yml
index 86a5691..8b80f7f 100644
--- a/.olddoc.yml
+++ b/.olddoc.yml
@@ -3,5 +3,4 @@ cgit_url: https://bogomips.org/kcar.git
 git_url: git://bogomips.org/kcar.git
 rdoc_url: https://bogomips.org/kcar/
 ml_url: https://bogomips.org/kcar-public/
-private_email: kcar@bogomips.org
 public_email: kcar-public@bogomips.org
diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..d3d54f8
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,37 @@
+== development dependencies
+
+* GNU make - https://www.gnu.org/software/make/
+* git - https://www.git-scm.com/
+* ruby - https://www.ruby-lang.org/en/
+
+	git clone git://bogomips.org/kcar
+
+== tests
+
+* make test - run each test in a separate process (parallelize using -j)
+
+For non-GNU users, GNU make may be installed as "gmake".
+
+== test environment
+
+N - specify the number of threads for *-mt targets (minitest parallelize_me!)
+RUBY - specify an alternative ruby(1) runtime
+V - set to 1 for verbose test output (may be mangled if multithreaded)
+
+== installing from git
+
+* make install-gem
+
+== contact
+
+We use git(7) and develop kcar on a public mailing list like git.git
+developers do.  Please send patches via git-send-email(1) to the public
+mailing list at <mailto:kcar-public@bogomips.org>.  Pull requests should be
+formatted using git-request-pull(1).
+
+All mail is archived publically at: https://bogomips.org/kcar-public/
+and nntp://news.public-inbox.org/inbox.comp.lang.ruby.kcar
+
+Anonymous contributions will always be welcome.
+No subscription is necessary to post to the mailing list.
+Please remember to Cc: all recipients as subscription is optional.
diff --git a/README b/README
index 85a9972..c735a76 100644
--- a/README
+++ b/README
@@ -83,8 +83,9 @@ don't email the git mailing list or maintainer with kcar patches.
 == Contact
 
 All feedback (bug reports, user/development discussion, patches, pull
-requests) go to the mailing list: mailto:kcar-public@bogomips.org
-
-Mailing list archives are available here:
-
-https://bogomips.org/kcar-public/
+requests) go to the public mailing list: mailto:kcar-public@bogomips.org
+All mail is archived publically at: https://bogomips.org/kcar-public/
+and nntp://news.public-inbox.org/inbox.comp.lang.ruby.kcar
+Anonymous requests will always be welcome.
+No subscription is necessary to post to the mailing list.
+Please remember to Cc: all recipients as subscription is optional.
diff --git a/kcar.gemspec b/kcar.gemspec
index 3d8d39d..ebabf06 100644
--- a/kcar.gemspec
+++ b/kcar.gemspec
@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.homepage = Olddoc.config['rdoc_url']
   s.authors = ["kcar hackers"]
   s.description = readme_description
-  s.email = %q{kcar@bogomips.org}
+  s.email = %q{kcar-public@bogomips.org}
   s.extra_rdoc_files = extra_rdoc_files(manifest)
   s.files = manifest
   s.summary = summary
-- 
EW

[PATCH] HACKING: remove copy+pasted line about N

[Eric Wong]

We are not using minitest, here.
---
 HACKING | 1 -
 1 file changed, 1 deletion(-)

diff --git a/HACKING b/HACKING
index d3d54f8..b56b686 100644
--- a/HACKING
+++ b/HACKING
@@ -14,7 +14,6 @@ For non-GNU users, GNU make may be installed as "gmake".
 
 == test environment
 
-N - specify the number of threads for *-mt targets (minitest parallelize_me!)
 RUBY - specify an alternative ruby(1) runtime
 V - set to 1 for verbose test output (may be mangled if multithreaded)
 
-- 
EW

[PATCH 2/6] doc: minor updates to describe classes, better

[Eric Wong]

---
 ext/kcar/kcar.rl     | 5 +++++
 lib/kcar/response.rb | 4 ++--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/ext/kcar/kcar.rl b/ext/kcar/kcar.rl
index ef3e393..2155ab4 100644
--- a/ext/kcar/kcar.rl
+++ b/ext/kcar/kcar.rl
@@ -718,6 +718,11 @@ void Init_kcar_ext(void)
   VALUE mKcar = rb_define_module("Kcar");
   VALUE cParser = rb_define_class_under(mKcar, "Parser", rb_cObject);
 
+  /*
+   * Document-class: Kcar::ParserError
+   *
+   * This is raised if there are parsing errors.
+   */
   eParserError = rb_define_class_under(mKcar, "ParserError", rb_eIOError);
 
   rb_define_alloc_func(cParser, kcar_alloc);
diff --git a/lib/kcar/response.rb b/lib/kcar/response.rb
index 954502c..c74bb4b 100644
--- a/lib/kcar/response.rb
+++ b/lib/kcar/response.rb
@@ -1,8 +1,8 @@
 # -*- encoding: binary -*-
 
 
-# This may be used to generate a Rack response
-#
+# This may be used to generate a Rack response synchronously.
+
 class Kcar::Response
   attr_accessor :sock, :hdr, :unchunk, :buf, :parser
 
-- 
EW

[PATCH 3/6] response: remove unnecessary constant alias

[Eric Wong]

Constant lookups are inline-cached in modern Rubies,
so this is a waste of memory.
---
 lib/kcar/response.rb | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/lib/kcar/response.rb b/lib/kcar/response.rb
index c74bb4b..af15ca0 100644
--- a/lib/kcar/response.rb
+++ b/lib/kcar/response.rb
@@ -6,10 +6,6 @@
 class Kcar::Response
   attr_accessor :sock, :hdr, :unchunk, :buf, :parser
 
-  # :stopdoc:
-  Parser = Kcar::Parser
-  # :startdoc:
-
   # By default we readpartial at most 16K off a socket at once
   READ_SIZE = 0x4000
 
@@ -17,7 +13,8 @@ class Kcar::Response
   # method.  +unchunk+ may be set to disable transparent unchunking
   # +hdr+ may be a Hash, Array, or Rack::Utils::HeaderHash
   def initialize(sock, hdr = {}, unchunk = true)
-    @sock, @hdr, @unchunk, @buf, @parser = sock, hdr, unchunk, "", Parser.new
+    @sock, @hdr, @unchunk, @buf =  sock, hdr, unchunk, ""
+    @parser = Kcar::Parser.new
   end
 
   # returns a 3-element array that resembles a Rack response, but is
-- 
EW

[PATCH 4/6] response: more documentation cleanups

[Eric Wong]

Our accessors are unfortunately set in stone, but there's no
need to document them.  The #each method should also yield
a meaningful variable name for RDoc.
---
 lib/kcar/response.rb | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/lib/kcar/response.rb b/lib/kcar/response.rb
index af15ca0..7fa804b 100644
--- a/lib/kcar/response.rb
+++ b/lib/kcar/response.rb
@@ -4,7 +4,9 @@
 # This may be used to generate a Rack response synchronously.
 
 class Kcar::Response
+  # :stopdoc:
   attr_accessor :sock, :hdr, :unchunk, :buf, :parser
+  # :startdoc:
 
   # By default we readpartial at most 16K off a socket at once
   READ_SIZE = 0x4000
@@ -60,11 +62,11 @@ class Kcar::Response
   def each
     return if @parser.body_eof?
     if @unchunk
-      @parser.chunked? ? each_unchunk { |x| yield x } :
-                         each_identity { |x| yield x }
+      @parser.chunked? ? each_unchunk { |buf| yield buf } :
+                         each_identity { |buf| yield buf }
     else
-      @parser.chunked? ? each_rechunk { |x| yield x } :
-                         each_identity { |x| yield x }
+      @parser.chunked? ? each_rechunk { |buf| yield buf } :
+                         each_identity { |buf| yield buf }
     end
   end
 
-- 
EW

[PATCH 5/6] favor require_relative to speed up loading

[Eric Wong]

require_relative reduces the path search which gets more
expensive as more RubyGems are available.
---
 lib/kcar.rb | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/kcar.rb b/lib/kcar.rb
index 55ac527..1929c21 100644
--- a/lib/kcar.rb
+++ b/lib/kcar.rb
@@ -3,6 +3,6 @@ module Kcar
   autoload :Response, 'kcar/response'
 end
 
-require 'kcar/version'
-require 'kcar/parser'
+require_relative 'kcar/version'
+require_relative 'kcar/parser'
 require 'kcar_ext'
-- 
EW

[PATCH 6/6] response: remove Ruby 1.8-compatibility check

[Eric Wong]

String#clear is available since Ruby 1.9.1+
---
 lib/kcar/response.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/kcar/response.rb b/lib/kcar/response.rb
index 7fa804b..58a7148 100644
--- a/lib/kcar/response.rb
+++ b/lib/kcar/response.rb
@@ -141,7 +141,7 @@ class Kcar::Response
           len -= @sock.readpartial(len > READ_SIZE ? READ_SIZE : len, dst).size
           yield dst
         end while len > 0
-        dst.respond_to?(:clear) ? dst.clear : @buf = ""
+        dst.clear
       end
     end
     @parser.body_bytes_left = 0
-- 
EW