# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1471915107 0
# Node ID a90a598db9e9842c88d573ef05fcf825e9950df5
# Parent  aa3afb09e9103d3bba9ea7139a5f10fe77a91560
Update docs

diff -r aa3afb09e910 -r a90a598db9e9 DOCUMENTATION.markdown
--- a/DOCUMENTATION.markdown	Tue Aug 23 01:13:16 2016 +0000
+++ b/DOCUMENTATION.markdown	Tue Aug 23 01:18:27 2016 +0000
@@ -220,7 +220,19 @@
 
 ### `BITS` (function)
 
-    (BITS N SIZE)
+    (BITS N SIZE &OPTIONAL (STREAM T))
+
+Print the bits of the `size`-bit two's complement integer `n` to `stream`.
+
+  Examples:
+
+    (bits 5 10)
+    => 0000000101
+
+    (bits -5 10)
+    => 1111111011
+
+  
 
 ### `DIS` (macro)
 
@@ -239,6 +251,12 @@
 
     (PR &REST ARGS)
 
+Print `args` readably, separated by spaces and followed by a newline.
+
+  This is what `print` should have been.
+
+  
+
 ## Package `LOSH.DISTRIBUTIONS`
 
 Utilities for calculating statistical... things.
@@ -727,7 +745,7 @@
     (MAKE-WEIGHTLIST ITEMS WEIGHTS)
 
 Make a weightlist of the given items and weights.
-  
+
   Weights can be any `real` numbers.  Weights of zero are fine, as long as at
   least one of the weights is nonzero (otherwise there's nothing to choose).
 
diff -r aa3afb09e910 -r a90a598db9e9 losh.lisp
--- a/losh.lisp	Tue Aug 23 01:13:16 2016 +0000
+++ b/losh.lisp	Tue Aug 23 01:18:27 2016 +0000
@@ -1159,13 +1159,29 @@
 
 ;;;; Debugging & Logging
 (defun pr (&rest args)
+  "Print `args` readably, separated by spaces and followed by a newline.
+
+  This is what `print` should have been.
+
+  "
   (format t "~{~S~^ ~}~%" args)
   (finish-output)
   (values))
 
-(defun bits (n size)
+(defun bits (n size &optional (stream t))
+  "Print the bits of the `size`-bit two's complement integer `n` to `stream`.
+
+  Examples:
+
+    (bits 5 10)
+    => 0000000101
+
+    (bits -5 10)
+    => 1111111011
+
+  "
   ;; http://blog.chaitanyagupta.com/2013/10/print-bit-representation-of-signed.html
-  (format t (format nil "~~~D,'0B" size) (ldb (byte size 0) n))
+  (format stream (format nil "~~~D,'0B" size) (ldb (byte size 0) n))
   (values))
 
 (defmacro dis (arglist &body body)
@@ -1188,7 +1204,7 @@
 
 (defun make-weightlist (items weights)
   "Make a weightlist of the given items and weights.
-  
+
   Weights can be any `real` numbers.  Weights of zero are fine, as long as at
   least one of the weights is nonzero (otherwise there's nothing to choose).