Add some documentation

diff --git a/mapi/README.org b/mapi/README.org
new file mode 100644 (file)
index 0000000..e785cd4
--- /dev/null
+++ b/mapi/README.org
@@ -0,0 +1,13 @@
+* mapi
+
+mapi is a thin library around the Matrix client-server API. With it you can
+create your own clients or bots that talk throught he Matrix API.
+
+** Current State
+
+The library is not finished and not production ready. It lacks proper
+documentation and a stable API. It also lacks support for most of the Matrix
+specification besides the bare minimum.
+
+That being said, most of the important logic can be read in `core.lisp` and maps
+fairly well to what you would expect from standard matrix bot sdk.

diff --git a/mapi/src/core.lisp b/mapi/src/core.lisp
index f4b2505bcb1e60f2375219cb62bc7f923ece120f..ed600ff9dadd0270028b59dacaf566b288eac7f0 100644 (file)
--- a/mapi/src/core.lisp
+++ b/mapi/src/core.lisp
@@ -48,6 +48,18 @@
   (:default-initargs :name "matrix-bot"))
 
 (defgeneric request (obj endpoint &rest rest)
   (:default-initargs :name "matrix-bot"))
 
 (defgeneric request (obj endpoint &rest rest)

+  (:documentation
+   "Make an http request to a Matrix homeserver
+
+Syntax: (REQUEST obj endpoint METHOD data headers)
+
+`endpoint` is a string path containing the matrix endpoint WITHOUT the protocol,
+           hostname, and /_matrix/client/v3
+`METHOD` is a symbol (e.g :get, :post, :put) that represents the HTTP method to be used
+`data` is a hash table, which will be sent as json
+`headers` is an alist containing additional headers to be sent.
+
+Usually with :post or :put you want to send the application/json content-type")

   (:method ((obj matrix-client) endpoint &rest rest &aux (headers))
     (declare (type string endpoint))
 
   (:method ((obj matrix-client) endpoint &rest rest &aux (headers))
     (declare (type string endpoint))
 


@@ -62,14 +74,26 @@
                                  :verbose nil))))
 
 (defgeneric on-event (obj event room-id)
                                  :verbose nil))))
 
 (defgeneric on-event (obj event room-id)

+  (:documentation
+   "Method that triggers every time an event is received via /sync.
+
+Does not run for the first call to /sync.
+
+You can use this to build your own architecture for listening for events.")

   (:method ((obj matrix-client) event room-id)
     (format t "Event Received: ~a~%" event)))
 
 (defgeneric whoami (obj)
   (:method ((obj matrix-client) event room-id)
     (format t "Event Received: ~a~%" event)))
 
 (defgeneric whoami (obj)

+  (:documentation
+   "Run a /_matrix/client/v3/account/whoami request, returning the resulting hash table")

   (:method ((obj matrix-client))
     (request obj "/account/whoami" :get)))
 
 (defgeneric directory-room (obj room-alias)
   (:method ((obj matrix-client))
     (request obj "/account/whoami" :get)))
 
 (defgeneric directory-room (obj room-alias)

+  (:documentation
+   "Run a /_matrix/client/v3/directory/room request, returning the resulting hash table
+
+This can be used to map a room alias to an ID, or get a list of homeservers that have the specific room.")

   (:method ((obj matrix-client) room-alias)
     (check-type room-alias room-alias)
     (request obj
   (:method ((obj matrix-client) room-alias)
     (check-type room-alias room-alias)
     (request obj


@@ -78,6 +102,8 @@
              :get)))
 
 (defgeneric join (obj room)
              :get)))
 
 (defgeneric join (obj room)

+  (:documentation)
+  (:document)

   (:method ((obj matrix-client) room)
     (request obj (format nil "/join/~a"
                          (quri:url-encode room))
   (:method ((obj matrix-client) room)
     (request obj (format nil "/join/~a"
                          (quri:url-encode room))