api.lisp

   1 ;;;; -*- Mode: LISP; Syntax: ANSI-Common-Lisp; Base: 10 -*-
   2 ;;;; *************************************************************************
   3 ;;;; FILE IDENTIFICATION
   4 ;;;;
   5 ;;;; Name:          api.lisp
   6 ;;;; Purpose:       Macros for generating API documentation
   7 ;;;; Programmer:    Kevin M. Rosenberg based on Matthew Danish's code
   8 ;;;; Date Started:  Nov 2002
   9 ;;;;
  10 ;;;; $Id: api.lisp,v 1.1 2002/11/08 06:00:12 kevin Exp $
  11 ;;;;
  12 ;;;; This file, part of LML, is Copyright (c) 2002 by Kevin M. Rosenberg
  13 ;;;; and Copyright (c) 2002 Matthew Danish
  14 ;;;;
  15 ;;;; LML users are granted the rights to distribute and use this software
  16 ;;;; as governed by the terms of the GNU General Public License v2
  17 ;;;; (http://www.gnu.org/licenses/gpl.html)
  18 ;;;; *************************************************************************
  19
  20 (declaim (optimize (debug 3) (speed 3) (safety 1) (compilation-speed 0)))
  21 (in-package :lml)
  22
  23 ;;; Copyright (c) 2002 Matthew Danish.
  24 ;;; All rights reserved.
  25
  26 ;;; Redistribution and use in source and binary forms, with or without
  27 ;;; modification, are permitted provided that the following conditions
  28 ;;; are met:
  29 ;;; 1. Redistributions of source code must retain the above copyright
  30 ;;;    notice, this list of conditions and the following disclaimer.
  31 ;;; 2. Redistributions in binary form must reproduce the above copyright
  32 ;;;    notice, this list of conditions and the following disclaimer in the
  33 ;;;    documentation and/or other materials provided with the distribution.
  34 ;;; 3. The name of the author may not be used to endorse or promote products
  35 ;;;    derived from this software without specific prior written permission.
  36 ;;;
  37 ;;; THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  38 ;;; IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  39 ;;; OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  40 ;;; IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  41 ;;; INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  42 ;;; NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  43 ;;; DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  44 ;;; THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  45 ;;; (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  46 ;;; THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  47
  48 ;;; For an example, see Matthew Danish's cl-ftp documentation at
  49 ;;; http://www.mapcar.org/~mrd/cl-sql/
  50
  51 (defmacro api-list (&body body)
  52   `(ul ,@(loop for item in body collect `(li ,item))))
  53
  54 (defun stringify (x)
  55   (let ((*print-case* :downcase))
  56     (if (null x)
  57         "()"
  58         (format nil "~A" x))))
  59
  60 (defmacro with-class-info ((class-name superclasses &rest slot-docs) &body other-info)
  61   `(p (i "Class ") (b ,(stringify class-name))
  62     (i " derived from ") ,(stringify superclasses) " -- " (br)
  63     (i "Initargs:") (br)
  64     (ul
  65      ,@(loop for (slot-name slot-desc slot-default) in slot-docs collect
  66              `(li (tt ,(format nil ":~A" slot-name))
  67                " -- " ,slot-desc " -- " (i "Default: ")
  68                ,(if (eql slot-default :n/a)
  69                     "Not specified"
  70                     (format nil "~S" slot-default)))))
  71     ,@other-info))
  72
  73 (defmacro with-macro-info ((macro-name &rest lambda-list) &body other-info)
  74   `(p (i "Macro ") (b ,(stringify macro-name)) " "
  75     (tt ,(stringify lambda-list)) (br)
  76     ,@other-info))
  77
  78 (defmacro with-function-info ((function-name &rest lambda-list) &body other-info)
  79   `(p (i "Function ") (b ,(stringify function-name)) " "
  80     (tt ,(stringify lambda-list))
  81     (br) ,@other-info))
  82
  83 (defmacro with-condition-info ((condition-name supers &rest slot-docs) &body other-info)
  84   `(p (i "Condition ") (b ,(stringify condition-name))
  85     (i " derived from ") ,(stringify supers) " -- " (br)
  86     (i "Slots:") (br)
  87     (ul
  88      ,@(loop for (slot-name slot-desc slot-reader slot-initarg slot-default) in slot-docs collect
  89              `(li (tt ,(stringify slot-name))
  90                " -- " ,slot-desc " -- " (i " Default: ")
  91                ,(if (eql slot-default :n/a)
  92                     "Not specified"
  93                     (format nil "~S" slot-default)))))
  94     ,@other-info))
  95
  96 (defmacro with-functions (&rest slots)
  97   `(progn ,@(loop for (fn description . args) in slots collect
  98                   `(with-function-info (,fn ,@(if args args
  99                                                   '(connection-variable)))
 100                     ,description))))