examples: flesh out the example configs a bit

Hopefully this makes things a little easier to pick up.

2 files changed, 16 insertions, 4 deletions

diff --git a/examples/yahns_multi.conf.rb b/examples/yahns_multi.conf.rb
index cdcb445..ecea565 100644
--- a/examples/yahns_multi.conf.rb
+++ b/examples/yahns_multi.conf.rb
@@ -1,20 +1,27 @@
 # To the extent possible under law, Eric Wong has waived all copyright and
 # related or neighboring rights to this example.
 
+# See yahns_config(5) manpage for more information
+
 # By default, this based on the soft limit of RLIMIT_NOFILE
 #   count = Process.getrlimit(:NOFILE)[0]) * 0.5
 # yahns will start expiring idle clients once we hit it
 client_expire_threshold 0.5
 
+# This is highly recommended if you're daemonizing yahns
+# Without it, Ruby backtrace logs can be lost.
+stderr_path "/path/to/stderr.log"
+
 # each queue definition configures a thread pool and epoll_wait usage
 # The default queue is always present
 queue(:default) do
-  worker_threads 7 # this is the default value
+  worker_threads 7 # this is the default value, highly app-dependent
   max_events 1 # 1: fairest, best in all multi-threaded cases
 end
 
 # This is an example of a small queue with fewer workers and unfair scheduling.
 # It is rarely necessary or even advisable to configure multiple queues.
+# Again, this is rarely necessary or even useful
 queue(:small) do
   worker_threads 2
 
@@ -25,10 +32,13 @@ queue(:small) do
   max_events 64
 end
 
-# This is an example of a Rack application configured in yahns
+# This is an example of a Rack application configured in yahns.
+# There must be at least one app configured for yahns to run.
 # All values below are defaults
 app(:rack, "/path/to/config.ru", preload: false) do
-  listen 8080, backlog: 1024, tcp_nodelay: false
+  # note: there is no listen default, this must be configured yourself
+  listen 8080, backlog: 1024
+
   client_max_body_size 1024*1024
   check_client_connection false
   logger Logger.new($stderr)
@@ -74,7 +84,7 @@ app(:rack, "/path/to/not_thread_safe.ru") do
   listen "/path/to/yet_another.sock"
   listen 8082
 
-  # inline private queue definition here
+  # inline private/anonymous queue definition here
   queue do
     worker_threads 1 # single-threaded queue
     max_events 64 # very high max_events is perfectly fair for single thread
diff --git a/examples/yahns_rack_basic.conf.rb b/examples/yahns_rack_basic.conf.rb
index 3364587..12bbc99 100644
--- a/examples/yahns_rack_basic.conf.rb
+++ b/examples/yahns_rack_basic.conf.rb
@@ -2,6 +2,8 @@
 # related or neighboring rights to this examples
 # A typical Rack example for hosting a single Rack application with yahns
 # and only frequently-useful config values
+#
+# See yahns_config(5) manpage for more information
 
 worker_processes(1) do
   # these names are based on pthread_atfork(3) documentation