From 1aed210f14a0016c33cd7c0ce606e536ea3266ed Mon Sep 17 00:00:00 2001
From: vindarel <vindarel@mailz.org>
Date: Tue, 20 Feb 2024 12:35:04 +0100
Subject: [PATCH] more docstrings++

---
 src/more-docstrings/README.md       |  14 +++-
 src/more-docstrings/docstrings.lisp | 108 ++++++++++++++++++++++++++++
 2 files changed, 120 insertions(+), 2 deletions(-)

diff --git a/src/more-docstrings/README.md b/src/more-docstrings/README.md
index d28ea54..fec5192 100644
--- a/src/more-docstrings/README.md
+++ b/src/more-docstrings/README.md
@@ -3,7 +3,7 @@ Augment the docstring of built-in functions and macros with more explanations an
 
 Let's see how useful it is for newcomers.
 
-This is part of CIEL (CIEL Is an Extended Lisp).
+This is part of [CIEL](https://github.com/ciel-lang/CIEL/) (CIEL Is an Extended Lisp).
 
 A few functions are done:
 
@@ -30,11 +30,21 @@ For many examples, see the CL Cookbook:
 https://lispcookbook.github.io/cl-cookbook/iteration.html
 ```
 
-- `mapcar`, `maphash`
+- `mapcar`, `mapcan`
+- `maphash`
 - `sort`
+- `loop`
+- `defun`, `defmacro`
+- `defclass`, `defgeneric`, `print-object`
+- `defstruct`
+- `find`
 
 and that's it. To be continued.
 
 A gotcha though:
 
 - we are modifying the symbols in the :cl package, there is currently no way to "undo" these additions.
+
+## Installation
+
+This library is on [Ultralisp](https://ultralisp.org/github).
diff --git a/src/more-docstrings/docstrings.lisp b/src/more-docstrings/docstrings.lisp
index 86a4a14..4b4a289 100644
--- a/src/more-docstrings/docstrings.lisp
+++ b/src/more-docstrings/docstrings.lisp
@@ -165,5 +165,113 @@ https://gigamonkeys.com/book/macros-standard-control-constructs.html
 https://www.youtube.com/watch?v=ygKXeLKhiTI Little bits of Lisp video
 ")
 
+;;; defclass
+(docstring-append 'defclass "The macro defclass defines a new named class. It returns the new class object as its result.
+
+Example:
+
+    (defclass living-being () ())
+
+    (defclass person (living-being)
+      ((name
+        :initarg :name
+        :initform \"\"
+        :accessor name)
+       (lisper
+        :initarg :lisper
+        :initform nil
+        :accessor lisper
+        :documentation \"Set to non-nil if this person fancies Lisp.\")))
+
+Slots are unbound by default, here we prefer them to be the empty string and nil.
+
+An :accessor creates a generic method. You can have the same accessor name in different classes.
+
+Create an instance of that class with MAKE-INSTANCE:
+
+    (make-instance 'person :name \"Alice\" :lisper t)
+
+Define how to pretty-print an object with PRINT-OBJECT.
+
+After we change a class definition (slots are modified, added or removed), we can control how an object is updated with UPDATE-INSTANCE-FOR-REDEFINED-CLASS.
+
+Read more:
+https://lispcookbook.github.io/cl-cookbook/clos.html
+https://cl-community-spec.github.io/pages/defclass.html
+")
 
 ;;; to be continued.
+
+(docstring-append 'print-object "The generic function print-object writes the printed representation of object to stream. The function print-object is called by the Lisp printer; it should not be called by the user.
+
+Example:
+
+   (defmethod print-object ((obj person) stream)
+      (print-unreadable-object (obj stream :type t :identity t)
+        (with-slots (name lisper) obj
+          (format stream \"~a, lisper: ~a\" name lisper))))
+
+   (make-instance 'person :name \"Alice\")
+   ;; =>
+   #<PERSON Alice, lisper: NIL {1007277633}>
+   (1) (2)                     (3)
+   1 tells the reader that this object can't be read back in
+   2 is the object type
+   3 is the object identity (address).
+
+Read more:
+https://cl-community-spec.github.io/pages/print_002dobject.html
+https://lispcookbook.github.io/cl-cookbook/clos.html#pretty-printing
+")
+
+(docstring-append 'defstruct "
+
+Example:
+
+  (defstruct person
+    name age)
+
+Creates the `make-person' constructor function, the `person-p' predicate as well as the `person-name' and `person-age' setf-able functions:
+
+   (person-name (make-person :name \"lisper\"))
+   ;; => \"lisper\"
+
+Read more:
+
+- https://lispcookbook.github.io/cl-cookbook/data-structures.html#structures
+- https://cl-community-spec.github.io/pages/defstruct.html")
+
+(docstring-append 'defgeneric "
+
+A generic function is a lisp function which is associated
+with a set of methods and dispatches them when it's invoked. All
+the methods with the same function name belong to the same generic
+function.
+
+The `defgeneric` form defines the generic function. If we write a
+`defmethod` without a corresponding `defgeneric`, a generic function
+is automatically created.
+
+Example:
+
+  (defgeneric greet (obj)
+    (:documentation \"says hi\")
+    (:method (obj)
+      (format t \"Hi\")))
+
+")
+
+(docstring-append 'find "
+Search for ITEM in SEQUENCE, return ITEM.
+
+Example:
+
+  (find 20 '(10 20 30)) ;; => 20
+  (find \"foo\" '(\"abc\" \"foo\") :test #'string-equal) ;; => \"foo\"
+
+See also: `find-if', `position', `search', `index', `elt'…
+
+Read more:
+
+- https://cl-community-spec.github.io/pages/find.html
+- https://lispcookbook.github.io/cl-cookbook/data-structures.html")