From 18d67e16348f3401a694a5a8d46af79610fadf49 Mon Sep 17 00:00:00 2001
From: Colin Okay <okay@toyful.space>
Date: Wed, 16 Feb 2022 16:59:59 -0600
Subject: added definitions to apps; appended definitions to generated docs

---
 example/lazybones-example-docs.md | 19 +++++++++++++++++--
 example/lazybones-example.lisp    | 15 +++++++++++++--
 lazybones-documentation.lisp      | 16 ++++++++++++++--
 lazybones.lisp                    | 17 +++++++++++++++++
 4 files changed, 61 insertions(+), 6 deletions(-)

diff --git a/example/lazybones-example-docs.md b/example/lazybones-example-docs.md
index 281b98c..a7dfca9 100644
--- a/example/lazybones-example-docs.md
+++ b/example/lazybones-example-docs.md
@@ -59,7 +59,7 @@ Route Variables:
 - PERSON: ID of a person
 
 
-Returns a json representation of the person.
+Returns a json representation of the [Person](#person).
 
 ### GET /random/:lo:/:hi:
 *text/plain*
@@ -81,4 +81,19 @@ Documented Query Parameters:
 - age: An Integer
 
 
-Echo the search parameters in a nice list.
\ No newline at end of file
+Echo the search parameters in a nice list.
+
+## Definitions
+
+<h3 id='#person'>Person</h3>
+
+An instance of person. As JSON, it looks like:
+
+    { 
+    "NAME" : string , 
+    "OCCUPATION" : string , 
+    "ID" : integer
+    }
+
+
+
diff --git a/example/lazybones-example.lisp b/example/lazybones-example.lisp
index 88a58a1..5eb00d9 100644
--- a/example/lazybones-example.lisp
+++ b/example/lazybones-example.lisp
@@ -58,7 +58,7 @@
   the \"true\" and sends a set-cookie header, setting 'testappsession'
   to 'coolsessionbro'."
   (print (lzb:request-body)) ; dummy implementation, prints post body to stdout
-  (setf (lzb:response-cookie "testappsession") "coolsessionbro")
+  (lzb:set-response-cookie "testappsession" "coolsessionbro" :path "/" :domain "localhost")
   "true")
 
 
@@ -121,6 +121,17 @@
 
 (defendpoint* :get "/person/:person person-by-id:" () 
   (:content-type "application/json")    ; override the app's default content type for HTTP responses
-  "Returns a json representation of the person."
+  "Returns a json representation of the [Person](#person)."
   (jonathan:to-json person))
 
+(lzb::set-definition
+ "Person" "#person"
+ "An instance of person. As JSON, it looks like:
+
+    { 
+    \"NAME\" : string , 
+    \"OCCUPATION\" : string , 
+    \"ID\" : integer
+    }
+
+")
diff --git a/lazybones-documentation.lisp b/lazybones-documentation.lisp
index 30ba6b6..48e55b2 100644
--- a/lazybones-documentation.lisp
+++ b/lazybones-documentation.lisp
@@ -14,7 +14,8 @@
            endpoints
            (default-authorizer authorizer)
            default-content-type
-           description)
+           description
+           definitions)
         app
       (with-output-to-string (*standard-output*) 
         (princ "# ") (princ title) (princ " - ") (princ "v") (princ version) 
@@ -55,7 +56,18 @@
                        (princ ": ") (princ (strip-newlines (documentation parser 'function)))
                        (princ #\newline)))
             newline
-            (princ endpoint-documentation) ))))))
+            (princ endpoint-documentation)))
+        newline
+        (when (plusp (hash-table-count definitions)) 
+          (princ "## Definitions") newline
+          (loop for name being the hash-key of definitions
+                for (node-id . text) being the hash-value of definitions
+                do (format *standard-output*
+                           "<h3 id='~a'>~a</h3>"
+                           node-id name)
+                   (princ #\newline) (princ #\newline)
+                   (princ text)
+                   (princ #\newline) (princ #\newline)))))))
 
 (defun ensure-blockquote (string)
   (concatenate 'string "> "
diff --git a/lazybones.lisp b/lazybones.lisp
index fe2ebc3..c7be8d8 100644
--- a/lazybones.lisp
+++ b/lazybones.lisp
@@ -57,6 +57,13 @@
     :initarg :vsn :initarg :version
     :initform "0.0.1"
     :type string)
+   (definitions
+    :accessor app-definitions
+    :initform (make-hash-table :test 'equal)
+    :documentation "Definitions are used in the generation of
+    documentation. They can be linked to from docstrings of
+    endpoints. Used to provide additional documentation for, e.g.,
+    JSON object specifications for post bodies or return types.")
    (authorizer
     :accessor request-authorizer
     :initarg :auth
@@ -379,3 +386,13 @@ making a new one if not."
   (signal 'http-error :content content :code code))
 
 
+;;; MANAGING DEFINITIONS
+
+(defun set-definition (name item-id definition-text &optional (app (lazybones:app)))
+  "Name is a string"
+  (setf (gethash name (app-definitions app)) (cons item-id definition-text)))
+
+(defun drop-definition (name &optional (app (lazybones:app)))
+  "Remove definition keyed by LINK-TARGET from APP."
+  (remhash name (app-definitions app)))
+
-- 
cgit v1.2.3