updating documentation generation

2 files changed, 46 insertions, 42 deletions

diff --git a/example/lazybones-test.lisp b/example/lazybones-test.lisp
index be50fc8..3c04065 100644
--- a/example/lazybones-test.lisp
+++ b/example/lazybones-test.lisp
@@ -10,12 +10,13 @@
 
 (in-package :lazybones-test)
 
-;; first make a server and add some custom error responses
+
+;; First make a server and add some custom error responses
 
 (defvar *server* (lzb:create-server :port 8888))
 
 (defun custom-404 ()
-  (format nil "~a wasn't found :(" (lzb:request-path))) ; can use request functiosn
+  (format nil "~a wasn't found :o~%" (lzb:request-path))) ; can use request functiosn
 
 (defun custom-403 ()
   "You, in particular, can't do that. :P ")
@@ -33,7 +34,7 @@
   :title "Lazybones Demo App"
   :version "0.0.0"
   :description "Just an API that defines some endpoints. These
-  endpoints aren't meant to accomplish anything. merely to test out
+  endpoints aren't meant to accomplish anything. Merely testing out
   the lazybones HTTP routing framework."
 
   :content-type "text/plain"   ; default content type of server responses.
@@ -60,56 +61,52 @@
   (http-ok "true"))
 
 (defendpoint* :get "/hello/:who:" () ()
-  "Just says hello to WHO"
-  (http-ok (format nil "Hello ~a" who)))
+  "Echos back Hello WHO"
+  (http-ok (format nil "Hello ~a~%" who)))
 
 (defendpoint* :post "/hello/:who:" ()  (:auth t)  ; use the default authorizor for the app
-  "Post something to hello who"
+  "Echo's back 'Hello WHO, I got your message BODY' where BODY is the post body."
   (print (lzb:request-header :content-type))
   (let ((body (lzb:request-body)))
-    (http-ok (format nil "Hello ~a, I got your message ~a"
+    (http-ok (format nil "Hello ~a, I got your message ~a~%"
                      who body))))
 
-(defendpoint* :get "/search" ((name identity) (age to-int)) ()
+;; Some helpers, these are used to parse url variables and query
+;; parameters. Their docstrings are used in the API documentation
+
+(defun int (string)
+  "An Integer"
+  (parse-integer string))
+
+(defun str (string)
+  "A String"
+  string)
+
+(defendpoint* :get "/search" ((name str) (age int)) ()
   "Echo the search parameters in a nice list."
   (http-ok (format nil "Name: ~a~%age: ~a~%" name age)))
 
-(defun crapshoot-authorizer () ()
+(defun crapshoot-authorizer ()
   "Randomly decides that the request is authorized" 
   (< 5 (random 10)))
 
-(defendpoint* :post "/search" () (:auth 'crapshoot-authorizer)  ; use custom authorizer
-  "Echo the search parameters in a nice list, but also has a post-body"
-  (http-ok
-   (with-output-to-string (out) 
-     (format out "Query Was:~%~{~a is ~a~%~}~%"
-             (loop for (x . y) in (lzb:request-parameters)
-                   collect x
-                   collect y))
-     (terpri)
-     (format out "Decoded Post Body: ~s~%" (lzb:request-body)))))
-
-
-(defun to-int (string)
-  "An Integer"
-  (parse-integer string))
+(defendpoint* :post "/crapshoot" () (:auth 'crapshoot-authorizer)  ; use custom authorizer
+  "Echos back 'You made it' if the request was authorized"
+  (http-ok "You made it"))
 
-;; route variables can accept parsers / preformatters
+;; Route variables can accept parsers / preformatters
 ;; these will parse a value and supply it to the argument of the handler.
-;; int eh following CATEGORY is an int
-
-(defendpoint* :get "/search/:category to-int:" () ()
-  "Echo the search back, but in a specific category"
-  (assert (typep category 'integer)) ; just to show you.
-  (http-ok 
-    (format nil "Searching in ~a with parameters:~%~{~a = ~a~%~}~%"
-                category
-                (loop for (x . y) in (lzb:request-parameters)
-                      collect x
-                      collect y))))
+
+(defendpoint* :get "/random/:lo int:/:hi int:" () ()
+  "Echo back a random number between lo and hi"
+  (if (< lo hi) 
+      (http-ok 
+       (format nil "The number is: ~a~%"
+               (+ lo (random (- hi lo)))))
+      (http-err 404))) ; Can't find a number X such that LO >= HI and LO < X < HI
 
 (defun person-by-id (id)
-  "A Person Instance"
+  "ID of a person"
   ;; The real thing might perform some database operation here. If the
   ;; operation failed, an error could be signalled, in which case a
   ;; 500 response would be sent to the client.
diff --git a/lazybones-documentation.lisp b/lazybones-documentation.lisp
index b64ec63..6527f41 100644
--- a/lazybones-documentation.lisp
+++ b/lazybones-documentation.lisp
@@ -23,7 +23,7 @@
         newline
         (princ "## Endpoints")
         (dolist (ep (sorted-endpoints endpoints))
-          (with-slots (method content-type route authorizer endpoint-documentation) ep
+          (with-slots (method content-type route authorizer params endpoint-documentation) ep
             newline 
             (princ "### ") (princ method) (princ " ") (princ (make-route-presentable route))
             (terpri)
@@ -36,9 +36,16 @@
               (dolist (var vars)
                 (princ "- ") (princ var)
                 (a:when-let (val-parser (route-var-value-parser ep var))
-                  (princ ": ") (princ (strip-newlines (documentation val-parser 'function)))))
-              newline)
-            
+                  (princ ": ") (princ (strip-newlines (documentation val-parser 'function))))
+                (princ #\newline)))
+            (when params
+              newline
+              (princ "Documented Query Parameters: ") newline
+              (loop for (var parser) in params
+                    do (princ "- ") (princ (string-downcase (symbol-name var)))
+                       (princ ": ") (princ (strip-newlines (documentation parser 'function)))
+                       (princ #\newline)))
+
             (when authorizer 
               (princ "Authorization Required: ")
               newline
@@ -47,7 +54,7 @@
                     ((function-or-function-name-p default-authorizer)
                      (princ (ensure-blockquote (documentation default-authorizer 'function)))))
               newline)
-
+            newline
             (princ endpoint-documentation) ))))))
 
 (defun ensure-blockquote (string)