From 1354ec43d848c6b26bd60b280b7dcc3252850d0b Mon Sep 17 00:00:00 2001
From: Colin Okay <okay@toyful.space>
Date: Sat, 12 Feb 2022 13:54:56 -0600
Subject: updating documentation generation

---
 example/lazybones-test.lisp | 71 ++++++++++++++++++++++-----------------------
 1 file changed, 34 insertions(+), 37 deletions(-)

(limited to 'example/lazybones-test.lisp')

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.
-- 
cgit v1.2.3