From c48361bb23ec21c672096104d6885c87f5ecbef6 Mon Sep 17 00:00:00 2001
From: colin <colin@cicadas.surf>
Date: Sat, 11 May 2024 13:10:04 -0700
Subject: Update: README. Add: print-all-route-documentation

---
 README.org                | 34 +++++++++++++---------------------
 examples/dice-roller.lisp |  2 +-
 examples/kitchensink.lisp |  6 ++++--
 src/endpoint.lisp         |  4 ++++
 src/package.lisp          |  7 +++++--
 5 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/README.org b/README.org
index e48cfe9..a7a1939 100644
--- a/README.org
+++ b/README.org
@@ -38,29 +38,21 @@ See [[./examples][examples]] for a few examples.
 
 ** Advantages of the Approach
 
-OOPyness is an advantage.  For example: you can easily recycle
-authentication and authorization by creating mix-in classes on which
-~authorize~ and ~authenticate~ are specialized. Anytime you want to
-add a new endpoint that must be authorized in a particular way, it is
-as easy as adding your mix-in to your new endpoint's superclasses.
+OOPyness is an advantage. Object orientation allows one to:
 
-The same thing applies to establishing and dis-establishing database
-connections - you simply specialize ~handle~'s ~:around~ method, or
-~:before~ and ~:after~ methods, on your endpoint class.
+- Recycle logic by defining protocol methods on mixin superclasses of
+  endponit classes. Whole regions of a site or API can easly be
+  extended or modified.
 
-If you want special processing on your endpoint classes themselves,
-you can sublcass the ~endpoint~ metaclass and specialize
-~intstantiate-instance~ methods.
+- ~ENDPOINT~ itself can be sublcassed for special endpoint definition
+  logic. E.g. ensuring a route prefix without having to type it each
+  time can be acheived by specializing ~instantiate-instance~ on a
+  subclass of ~ENDPOINT~.
 
-For example, if you would prefer every endpoint to be be prefixed by a
-particular route string, you can transform the ~route-parts~ field
-before they are processed by ~endpoint~'s ~instantiate-instance~
-method.
+- You can use the reified endpoints to automatically generate nice
+  documentation. (Less than nice documentation is already provided via
+  the function ~weekend:print-all-route-documentation~.)
 
-** Disadvantages of the Approach
-
-WEEKEND can be be a little verbose. You are free to define your own
-class-defining macros.
-
-This version of weekend is strongly tied to Hunchentoot.
+- Similarly, you can automatically generate API client code for your
+  langauge of choice.
 
diff --git a/examples/dice-roller.lisp b/examples/dice-roller.lisp
index d87faf4..465d252 100644
--- a/examples/dice-roller.lisp
+++ b/examples/dice-roller.lisp
@@ -20,7 +20,7 @@
     :initform (wknd:slot-required 'roller 'rolls)
     :type integer
     :documentation "The number of sides"))
-  (:documentation "")
+  (:documentation "Rolls a virtual dices with SIDES sides ROLLS number of times.")
   (:metaclass wknd::endpoint)
   (:method . :get)
   (:route-parts "roll" +digits+ "d" +digits+)
diff --git a/examples/kitchensink.lisp b/examples/kitchensink.lisp
index 00a7f25..7fcf45b 100644
--- a/examples/kitchensink.lisp
+++ b/examples/kitchensink.lisp
@@ -54,7 +54,8 @@
 
 (defclass hello ()
   ()
-  (:documentation "A Page that just says hello.")
+  (:documentation "A Page that just says hello to an identified user. Redirects users to
+identify themselves if no name is known.")
   (:metaclass wknd:endpoint)
   (:method . :get)
   (:route-parts "hello")
@@ -74,7 +75,8 @@
   ((name :reader name :initarg :name :type string))
   (:metaclass wknd::endpoint)
   (:method . :post)
-  (:route-parts "identify"))
+  (:route-parts "identify")
+  (:documentation "Endpoint for identifying oneself."))
 
 (defmethod wknd::handle ((req identify))
   (wknd:set-cookie "name" :value (name req))
diff --git a/src/endpoint.lisp b/src/endpoint.lisp
index 9064c9f..4f44a41 100644
--- a/src/endpoint.lisp
+++ b/src/endpoint.lisp
@@ -141,6 +141,10 @@ endpoints are dispatching on which routes and methods.")
         (terpri)
         (princ doc)))))
 
+(defun print-all-route-documentation (&key (stream *standard-output*))
+  (loop :for class :being :the :hash-keys :of *endpoint-registry*
+        :do (print-route-documentation class :stream stream)
+            (terpri stream)))
 
 ;;; BODY PARSER REGISTRATION
 
diff --git a/src/package.lisp b/src/package.lisp
index e8f56b3..bb74e5f 100644
--- a/src/package.lisp
+++ b/src/package.lisp
@@ -29,8 +29,11 @@
    #:handle-static-file
    #:set-cookie
 
-
    ;; METACLASS
    #:endpoint
-   #:register-body-parser))
+   #:register-body-parser
+
+   ;; DOCGEN
+   #:print-route-documentation
+   #:print-all-route-documentation))
 
-- 
cgit v1.2.3