From fae92b7249ea132305cee3c16b4667d4271cf09c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lui=CC=81s=20Oliveira?= Date: Wed, 4 Jan 2012 01:25:33 +0000 Subject: [PATCH] Document using atdoc. --- README | 28 +------ doc/index.css | 178 +++++++++++++++++++++++++++++++++++++++++++ gendocs.lisp | 14 ++++ trivial-garbage.asd | 2 - trivial-garbage.lisp | 105 ++++++++++++++++++------- 5 files changed, 272 insertions(+), 55 deletions(-) create mode 100644 doc/index.css create mode 100644 gendocs.lisp diff --git a/README b/README index e3430a2..e32f544 100644 --- a/README +++ b/README @@ -1,27 +1,5 @@ -trivial-garbage is a simple library that provides a portable API to -finalizers, weak hash-tables and weak pointers. +trivial-garbage provides a portable API to finalizers, weak hash-tables and +weak pointers on all major implementations of the Common Lisp programming +language. It is placed in the public domain with absolutely no warranty. - -The various bits of funcionality (finalizers, weak pointers, etc...) -are mutually independent. Feel free to copy whatever bits you find -useful into your own program. - -Documentation is generated with the code below and is available at -. - -(asdf:oos 'asdf:load-op :trivial-garbage) -(require :sb-introspect) - -(let ((syms nil)) - (do-external-symbols (sym :trivial-garbage) - (push sym syms)) - (flet ((snd (sym) (string-downcase (symbol-name sym)))) - (setq syms (sort syms #'string< :key #'snd)) - (dolist (sym syms) - (format t "

— Function: tg:~A" (snd sym)) - (format t "~{ ~A~}

~%" - (loop for arg in (sb-introspect:function-arglist sym) collect - (if (listp arg) (mapcar #'snd arg) (snd arg)))) - (format t "

~A

~%~%" - (documentation sym 'function))))) diff --git a/doc/index.css b/doc/index.css new file mode 100644 index 0000000..a1a2adf --- /dev/null +++ b/doc/index.css @@ -0,0 +1,178 @@ +/* based on atdoc's orange-sans.css */ + +div.sidebar { + float: right; + min-width: 15%; + padding: 0pt 5pt 5pt 5pt; + font-family: verdana, arial; +} + +a { + text-decoration: none; + color: #ee8500; +/* + border-bottom: 1px dotted black; + border-top: 1px solid white; + border-left: 1px solid white; + border-right: 1px solid white; + padding-top: 1px; + padding-bottom: 1px; +*/ +} + +.nonlink { + border-bottom: 1px solid white; + border-top: 1px solid white; + border-left: 1px solid white; + border-right: 1px solid white; + padding-top: 1px; + padding-bottom: 1px; +} + +.sidebar a { + border-top: 1px solid #eeeeee; + border-left: 1px solid #eeeeee; + border-right: 1px solid #eeeeee; +} + +/* +a:hover { + color: #000000; + border: 1px solid black; +} +*/ + +#headerlink { + border: none; +} + +#headerlink:hover { + border: none; +} + +body { + color: #000000; + background-color: #ffffff; + margin-top: 2em; + margin-right: 10em; + margin-left: 10em; + font-family: helvetica, verdana, arial; +} + +.main { + margin-top: 20px; + margin-left: 40px; +} + +.padded { + padding-left: 30px; +} + +.padded h1,h2 { + margin-left: -30px; +} + +h1 { + color: #ee8500; + font-size: 22pt; +} + +h3 { + color: #000000; + border-bottom: 2px solid #ff9500; + margin-left: -3px; + padding-left: 3px; + padding-top: 2em; +} + +h4 { +} + +.grau { + padding-top: 1em; +} + +.code { + border: solid 1px #d0d0d0; + padding: 1em; + margin-right: 10%; +} + +.indent { + /*margin-left: 20px; + padding-bottom: 1em;*/ +} + +.def { + padding: 1px 1px 1px 1px; + margin-bottom: 1px; + font-weight: bold; + margin-right: 40px; +} + +.nomargin { + margin-bottom: 0; + margin-top: 0; +} + +.noindent { + margin-left: -30px; + padding-bottom: 1em; +} + +#header { + margin-right: 22px; + /*border-bottom: 1px solid black;*/ + font-family: verdana, arial; + font-size: 18pt; + padding-bottom: 1px; +} + +pre { + background-color: #eeeeee; + border: solid 1px #d0d0d0; + padding: 1em; + margin-right: 10%; +} +#sp-package-list { + /* ... */ +} + +#sp-about-packages { + /* ... */ +} + +.sp-lambda-list { + background-color: #f4f4f4; + padding: 3px 3px 3px 3px; +} + +.sp-definition { + border: 1px solid #cccccc; + padding: 3px 3px 3px 3px; +} + +.sp-definition-body { + padding-left: 2em; + padding-right: 2em; + padding-top: 0.5em; + padding-bottom: 1em; +} + +.sp-definition-body ul { + margin-top: 0; + margin-bottom: 0; +} + +.sp-return { +} + +.sph3 { + padding-top: 1em; + font-weight: bold; +} + +#about-package-legend { display: none } +#contents { display: none } +.function-details-legend { display: none } +#heading2 { display: none } diff --git a/gendocs.lisp b/gendocs.lisp new file mode 100644 index 0000000..4e9058a --- /dev/null +++ b/gendocs.lisp @@ -0,0 +1,14 @@ +(in-package :cl-user) + +(asdf:load-system :atdoc) + +(let* ((base (asdf:component-pathname (asdf:find-system :trivial-garbage))) + (output-directory (merge-pathnames "doc/" base)) + (css-file (merge-pathnames "doc/index.css" base))) + (ensure-directories-exist output-directory) + (atdoc:generate-html-documentation '(:trivial-garbage) + output-directory + :single-page-p t + :heading "Trivial Garbage" + :index-title "Trivial Garbage" + :css css-file)) diff --git a/trivial-garbage.asd b/trivial-garbage.asd index 375d1dc..4559788 100644 --- a/trivial-garbage.asd +++ b/trivial-garbage.asd @@ -28,5 +28,3 @@ (sys (eql (find-system :trivial-garbage-tests)))) (operate 'load-op :trivial-garbage-tests) (funcall (find-symbol (string '#:do-tests) '#:rtest))) - -;; vim: ft=lisp et diff --git a/trivial-garbage.lisp b/trivial-garbage.lisp index e22af91..8578a4b 100644 --- a/trivial-garbage.lisp +++ b/trivial-garbage.lisp @@ -17,14 +17,61 @@ #:make-weak-hash-table #:hash-table-weakness #:finalize - #:cancel-finalization)) + #:cancel-finalization) + (:documentation + "@a[http://common-lisp.net/project/trivial-garbage]{trivial-garbage} + provides a portable API to finalizers, weak hash-tables and weak + pointers on all major implementations of the Common Lisp + programming language. For a good introduction to these + data-structures, have a look at + @a[http://www.haible.de/bruno/papers/cs/weak/WeakDatastructures-writeup.html]{Weak + References: Data Types and Implementation} by Bruno Haible. + + Source code is available at + @a[https://github.com/trivial-garbage/trivial-garbage]{github}, + which you are welcome to use for submitting patches and/or + @a[https://github.com/trivial-garbage/trivial-garbage/issues]{bug + reports}. Discussion takes place on + @a[http://lists.common-lisp.net/cgi-bin/mailman/listinfo/trivial-garbage-devel]{trivial-garbage-devel at common-lisp.net}. + + @begin[Weak Pointers]{section} + A @em{weak pointer} holds an object in a way that does not prevent + it from being reclaimed by the garbage collector. An object + referenced only by weak pointers is considered unreachable (or + \"weakly reachable\") and so may be collected at any time. When + that happens, the weak pointer's value becomes @code{nil}. + + @aboutfun{make-weak-pointer} + @aboutfun{weak-pointer-value} + @aboutfun{weak-pointer-p} + @end{section} + + @begin[Weak Hash-Tables]{section} + A @em{weak hash-table} is one that weakly references its keys + and/or values. When both key and value are unreachable (or weakly + reachable) that pair is reclaimed by the garbage collector. + + @aboutfun{make-weak-hash-table} + @aboutfun{hash-table-weakness} + @end{section} + + @begin[Finalizers]{section} + A @em{finalizer} is a hook that is executed after a given object + has been reclaimed by the garbage collector. + + @aboutfun{finalize} + @aboutfun{cancel-finalization} + @end{section}")) (in-package #:trivial-garbage) ;;;; GC (defun gc (&key full verbose) - "Initiates a garbage collection." + "Initiates a garbage collection. @code{full} forces the collection + of all generations, when applicable. When @code{verbose} is + @em{true}, diagnostic information about the collection is printed + if possible." (declare (ignorable verbose full)) #+(or cmu scl) (ext:gc :verbose verbose :full full) #+sbcl (sb-ext:gc :full full) @@ -46,8 +93,8 @@ #-openmcl pointer) (defun make-weak-pointer (object) - "Creates a new weak pointer which points to OBJECT. For - portability reasons, OBJECT must not be NIL." + "Creates a new weak pointer which points to @code{object}. For + portability reasons, @code{object} must not be @code{nil}." (assert (not (null object))) #+sbcl (sb-ext:make-weak-pointer object) #+(or cmu scl) (ext:make-weak-pointer object) @@ -70,7 +117,8 @@ #-(or allegro openmcl lispworks) (defun weak-pointer-p (object) - "Returns true if OBJECT is a weak pointer and NIL otherwise." + "Returns @em{true} if @code{object} is a weak pointer and @code{nil} + otherwise." #+sbcl (sb-ext:weak-pointer-p object) #+(or cmu scl) (ext:weak-pointer-p object) #+clisp (ext:weak-pointer-p object) @@ -79,7 +127,8 @@ #+corman (ccl:weak-pointer-p object)) (defun weak-pointer-value (weak-pointer) - "If WEAK-POINTER is valid, returns its value. Otherwise, returns NIL." + "If @code{weak-pointer} is valid, returns its value. Otherwise, + returns @code{nil}." #+sbcl (values (sb-ext:weak-pointer-value weak-pointer)) #+(or cmu scl) (values (ext:weak-pointer-value weak-pointer)) #+clisp (values (ext:weak-pointer-value weak-pointer)) @@ -106,11 +155,11 @@ (defvar *weakness-warnings* '() "List of weaknesses that have already been warned about this - session. Used by `weakness-missing'.") + session. Used by `weakness-missing'.") (defun weakness-missing (weakness errorp) "Signal an error or warning, depending on ERRORP, about lack of Lisp -support for WEAKNESS." + support for WEAKNESS." (cond (errorp (error "Your Lisp does not support weak ~(~A~) hash-tables." weakness)) @@ -146,15 +195,17 @@ support for WEAKNESS." (defun make-weak-hash-table (&rest args &key weakness (weakness-matters t) #+openmcl (test #'eql) &allow-other-keys) - "Returns a new weak hash table. In addition to the standard arguments - accepted by CL:MAKE-HASH-TABLE, this function adds extra - keywords: :WEAKNESS being the kind of weak table it should create, and - :WEAKNESS-MATTERS being whether an error should be signalled when that - weakness isn't available (the default is to signal an error). WEAKNESS - can be one of :KEY, :VALUE, :KEY-OR-VALUE, :KEY-AND-VALUE. - - TG::MAKE-HASH-TABLE is available as an alias for this function should you - wish to import it into your package and shadow CL:MAKE-HASH-TABLE." + "Returns a new weak hash table. In addition to the standard + arguments accepted by @code{cl:make-hash-table}, this function adds + extra keywords: @code{:weakness} being the kind of weak table it + should create, and @code{:weakness-matters} being whether an error + should be signalled when that weakness isn't available (the default + is to signal an error). @code{weakness} can be one of @code{:key}, + @code{:value}, @code{:key-or-value}, @code{:key-and-value}. + + @code{tg::make-hash-table} is available as an alias for this + function should you wish to import it into your package and shadow + @code{cl:make-hash-table}." (remf args :weakness) (remf args :weakness-matters) (if weakness @@ -178,7 +229,8 @@ support for WEAKNESS." (apply #'make-weak-hash-table args)) (defun hash-table-weakness (ht) - "Returns one of NIL, :KEY, :VALUE, :KEY-OR-VALUE or :KEY-AND-VALUE." + "Returns one of @code{nil}, @code{:key}, @code{:value}, + @code{:key-or-value} or @code{:key-and-value}." #-(or allegro sbcl abcl clisp cmu openmcl lispworks) (declare (ignore ht)) ;; keep this first if any of the other lisps bugously insert a NIL @@ -200,9 +252,6 @@ support for WEAKNESS." ;;;; Finalizers -;;; The fact that SBCL/CMUCL throw away the object *before* running -;;; the finalizer is somewhat unfortunate... - ;;; Note: Lispworks can't finalize gensyms. #+(or allegro clisp lispworks openmcl) @@ -230,13 +279,13 @@ support for WEAKNESS." (mapc #'funcall finalizers))))) (defun finalize (object function) - "Pushes a new FUNCTION to the OBJECT's list of - finalizers. FUNCTION should take no arguments. Returns OBJECT. + "Pushes a new @code{function} to the @code{object}'s list of + finalizers. @code{function} should take no arguments. Returns + @code{object}. - For portability reasons, FUNCTION should not attempt to look - at OBJECT by closing over it because, in some lisps, OBJECT - will already have been garbage collected and is therefore not - accessible when FUNCTION is invoked." + @b{Note:} @code{function} should not attempt to look at + @code{object} by closing over it because that will prevent it from + being garbage collected." #+(or cmu scl) (ext:finalize object function) #+sbcl (sb-ext:finalize object function) #+abcl (ext:finalize object function) @@ -300,7 +349,7 @@ support for WEAKNESS." object)) (defun cancel-finalization (object) - "Cancels all of OBJECT's finalizers, if any." + "Cancels all of @code{object}'s finalizers, if any." #+cmu (ext:cancel-finalization object) #+scl (ext:cancel-finalization object nil) #+sbcl (sb-ext:cancel-finalization object)