[mcclim-cvs] CVS mcclim/Drei

[thenriksen]

Update of /project/mcclim/cvsroot/mcclim/Drei
In directory clnet:/tmp/cvs-serv3308

Modified Files:
	buffer.lisp 
Log Message:
More docstring fixes and additions.


--- /project/mcclim/cvsroot/mcclim/Drei/buffer.lisp	2006/11/16 19:22:38	1.2
+++ /project/mcclim/cvsroot/mcclim/Drei/buffer.lisp	2006/11/18 15:42:43	1.3
@@ -31,22 +31,31 @@
 (in-package :drei-buffer)
 
 (defclass buffer () ()
-  (:documentation "The base class for all buffers. A buffer conceptually contains a
-large array of arbitrary objects.  Lines of objects are separated by
-newline characters.  The last object of the buffer is not
-necessarily a newline character."))
-
-(defgeneric low-mark (buffer))
-
-(defgeneric high-mark (buffer))
-
-(defgeneric modified-p (buffer))
+  (:documentation "The base class for all buffers. A buffer
+conceptually contains a large array of arbitrary objects.  Lines
+of objects are separated by newline characters.  The last object
+of the buffer is not necessarily a newline character."))
+
+(defgeneric low-mark (buffer)
+  (:documentation "Return the low mark of the buffer."))
+
+(defgeneric high-mark (buffer)
+  (:documentation "Return the high mark of the buffer."))
+
+(defgeneric modified-p (buffer)
+  (:documentation "Return true if and only if the buffer has been
+modified."))
 
 (defclass standard-buffer (buffer)
   ((contents :initform (make-instance 'standard-cursorchain))
-   (low-mark :reader low-mark)
-   (high-mark :reader high-mark)
-   (modified :initform nil :reader modified-p))
+   (low-mark :reader low-mark
+             :documentation "The low mark of the buffer.")
+   (high-mark :reader high-mark
+              :documentation "The high mark of the buffer.")
+   (modified :initform nil
+             :reader modified-p
+             :documentation "True if and only if the buffer has
+been modified."))
   (:documentation "The standard instantiable class for buffers."))
 
 (defgeneric buffer (mark)
@@ -72,11 +81,14 @@
 
 (defgeneric (setf offset) (new-offset mark)
   (:documentation "Set the offset of the mark into the buffer.  A
-no-such-offset condition is signaled if the offset is less than
-zero or greater than the size of the buffer."))
+motion-before-beginning condition is signaled if the offset is
+less than zero. A motion-after-end condition is signaled if the
+offset is greater than the size of the buffer."))
 
 (defclass mark-mixin ()
-  ((buffer :initarg :buffer :reader buffer)
+  ((buffer :initarg :buffer
+           :reader buffer
+           :documentation "The buffer that the mark is in.")
    (cursor :reader cursor))
   (:documentation "A mixin class used in the initialization of a mark."))
 
@@ -135,12 +147,26 @@
   (setf (cursor-pos (cursor mark)) new-offset))
 
 (defgeneric backward-object (mark &optional count)
-  (:documentation "Move `mark' `count' objects backwards. Returns
-  `mark'."))
+  (:documentation "Move the mark backward the number of positions
+indicated by count.  This function could be implemented by a
+`decf' on the offset of the mark, but many buffer implementations
+can implement this function much more efficiently in a different
+way. A `motion-before-beginning' condition is signaled if the
+resulting offset of the mark is less than zero. A
+motion-after-end condition is signaled if the resulting offset of
+the mark is greater than the size of the buffer. Returns
+`mark'."))
 
 (defgeneric forward-object (mark &optional count)
-  (:documentation "Move `mark' `count' objects forwards. Returns
-  `mark'"))
+  (:documentation "Move the mark forward the number of positions
+indicated by count.  This function could be implemented by an
+`incf' on the offset of the mark, but many buffer implementations
+can implement this function much more efficiently in a different
+way.  A `motion-before-beginning' condition is signaled if the
+resulting offset of the mark is less than zero. A
+`motion-after-end' condition is signaled if the resulting offset
+of the mark is greater than the size of the buffer. Returns
+`mark'."))
 
 (defmethod forward-object ((mark mark-mixin) &optional (count 1))
   (incf (offset mark) count)
@@ -226,10 +252,10 @@
 	count (eql (buffer-object buffer offset) #\Newline)))
 
 (defgeneric mark< (mark1 mark2)
-  (:documentation "Return t if the offset of mark1 is strictly less than that of mark2.
-An error is signaled if the two marks are not positioned in the same
-buffer.  It is acceptable to pass an offset in place of one of the
-marks"))
+  (:documentation "Return T if the offset of `mark1' is strictly
+less than that of `mark2'.  An error is signaled if the two marks
+are not positioned in the same buffer.  It is acceptable to pass
+an offset in place of one of the marks."))
 
 (defmethod mark< ((mark1 mark-mixin) (mark2 mark-mixin))
   (assert (eq (buffer mark1) (buffer mark2)))
@@ -242,10 +268,10 @@
   (< mark1 (offset mark2)))
 
 (defgeneric mark<= (mark1 mark2)
-  (:documentation "Return t if the offset of mark1 is less than or equal to that of
-mark2.  An error is signaled if the two marks are not positioned in
-the same buffer.  It is acceptable to pass an offset in place of one
-of the marks."))
+  (:documentation "Return T if the offset of `mark1' is less than
+or equal to that of `mark2'.  An error is signaled if the two
+marks are not positioned in the same buffer.  It is acceptable to
+pass an offset in place of one of the marks."))
 
 (defmethod mark<= ((mark1 mark-mixin) (mark2 mark-mixin))
   (assert (eq (buffer mark1) (buffer mark2)))
@@ -258,9 +284,10 @@
   (<= mark1 (offset mark2)))
 
 (defgeneric mark= (mark1 mark2)
-  (:documentation "Return t if the offset of mark1 is equal to that of mark2.  An error
- is signaled if the two marks are not positioned in the same buffer.
- It is acceptable to pass an offset in place of one of the marks."))
+  (:documentation "Return T if the offset of `mark1' is equal to
+that of `mark2'.  An error is signaled if the two marks are not
+positioned in the same buffer.  It is acceptable to pass an
+offset in place of one of the marks."))
 
 (defmethod mark= ((mark1 mark-mixin) (mark2 mark-mixin))
   (assert (eq (buffer mark1) (buffer mark2)))
@@ -273,10 +300,10 @@
   (= mark1 (offset mark2)))
 
 (defgeneric mark> (mark1 mark2)
-  (:documentation "Return t if the offset of mark1 is strictly greater than that of
-mark2.  An error is signaled if the two marks are not positioned in
-the same buffer.  It is acceptable to pass an offset in place of one
-of the marks."))
+  (:documentation "Return T if the offset of `mark1' is strictly
+greater than that of `mark2'.  An error is signaled if the two
+marks are not positioned in the same buffer.  It is acceptable to
+pass an offset in place of one of the marks."))
 
 (defmethod mark> ((mark1 mark-mixin) (mark2 mark-mixin))
   (assert (eq (buffer mark1) (buffer mark2)))
@@ -289,10 +316,10 @@
   (> mark1 (offset mark2)))
 
 (defgeneric mark>= (mark1 mark2)
-  (:documentation "Return t if the offset of mark1 is greater than or equal to that of
-mark2.  An error is signaled if the two marks are not positioned in
-the same buffer.  It is acceptable to pass an offset in place of one
-of the marks."))
+  (:documentation "Return T if the offset of `mark1' is greater
+than or equal to that of `mark2'.  An error is signaled if the
+two marks are not positioned in the same buffer.  It is
+acceptable to pass an offset in place of one of the marks."))
 
 (defmethod mark>= ((mark1 mark-mixin) (mark2 mark-mixin))
   (assert (eq (buffer mark1) (buffer mark2)))
@@ -306,8 +333,8 @@
 
 (defgeneric beginning-of-buffer (mark)
   (:documentation "Move the mark to the beginning of the buffer.
-  This is equivalent to (setf (offset mark) 0), but returns
-  mark."))
+This is equivalent to `(setf (offset mark) 0)', but returns
+mark."))
 
 ;; Easy way to make sure mark is always returned.
 (defmethod beginning-of-buffer :around (mark)
@@ -319,7 +346,7 @@
 
 (defgeneric end-of-buffer (mark)
   (:documentation "Move the mark to the end of the buffer and
-  return mark."))
+return mark."))
 
 (defmethod end-of-buffer :around (mark)
   (call-next-method)
@@ -329,41 +356,44 @@
   (setf (offset mark) (size (buffer mark))))
 
 (defgeneric beginning-of-buffer-p (mark)
-  (:documentation "Return t if the mark is at the beginning of
- the buffer, nil otherwise."))
+  (:documentation "Return T if the mark is at the beginning of
+the buffer, nil otherwise."))
 
 (defmethod beginning-of-buffer-p ((mark mark-mixin))
   (zerop (offset mark)))
 
 (defgeneric end-of-buffer-p (mark)
-  (:documentation "Return t if the mark is at the end of the buffer, nil otherwise."))
+  (:documentation "Return T if the mark is at the end of the
+buffer, NIL otherwise."))
 
 (defmethod end-of-buffer-p ((mark mark-mixin))
   (= (offset mark) (size (buffer mark))))
 
 (defgeneric beginning-of-line-p (mark)
-  (:documentation "Return t if the mark is at the beginning of the line (i.e., if the
-character preceding the mark is a newline character or if the mark is
-at the beginning of the buffer), nil otherwise."))
+  (:documentation "Return T if the mark is at the beginning of
+the line (i.e., if the character preceding the mark is a newline
+character or if the mark is at the beginning of the buffer), NIL
+otherwise."))
 
 (defmethod beginning-of-line-p ((mark mark-mixin))
   (or (beginning-of-buffer-p mark)
       (eql (object-before mark) #\Newline)))
 
 (defgeneric end-of-line-p (mark)
-  (:documentation "Return t if the mark is at the end of the line (i.e., if the character
-following the mark is a newline character, or if the mark is at the
-end of the buffer), nil otherwise."))
+  (:documentation "Return T if the mark is at the end of the
+line (i.e., if the character following the mark is a newline
+character, or if the mark is at the end of the buffer), NIL
+otherwise."))
 
 (defmethod end-of-line-p ((mark mark-mixin))
   (or (end-of-buffer-p mark)
       (eql (object-after mark) #\Newline)))
 
 (defgeneric beginning-of-line (mark)
-  (:documentation "Move the mark to the beginning of the line.  The mark will be
- positioned either immediately after the closest preceding newline
- character, or at the beginning of the buffer if no preceding newline
- character exists. Returns mark."))
+  (:documentation "Move the mark to the beginning of the line.
+The mark will be positioned either immediately after the closest
+receding newline character, or at the beginning of the buffer if
+no preceding newline character exists. Returns `mark'."))
 
 (defmethod beginning-of-line :around (mark)
   (call-next-method)
@@ -374,9 +404,10 @@
 	do (backward-object mark)))
 
 (defgeneric end-of-line (mark)
-  (:documentation "Move the mark to the end of the line. The mark will be positioned
-either immediately before the closest following newline character, or
-at the end of the buffer if no following newline character exists. Returns mark."))
+  (:documentation "Move the mark to the end of the line. The mark
+will be positioned either immediately before the closest
+following newline character, or at the end of the buffer if no
+following newline character exists. Returns `mark'."))
 
 (defmethod end-of-line :around (mark)
   (call-next-method)
@@ -393,17 +424,18 @@
     (setf (offset mark) offset)))
 
 (defgeneric buffer-line-number (buffer offset)
-  (:documentation "Return the line number of the offset.  Lines are numbered from zero."))
+  (:documentation "Return the line number of the offset.  Lines
+are numbered from zero."))
 
 (defmethod buffer-line-number ((buffer standard-buffer) (offset integer))
   (loop for i from 0 below offset
 	count (eql (buffer-object buffer i) #\Newline)))
 
 (defgeneric buffer-column-number (buffer offset)
-  (:documentation "Return the column number of the offset. The column number of an offset is
- the number of objects between it and the preceding newline, or
- between it and the beginning of the buffer if the offset is on the
- first line of the buffer."))
+  (:documentation "Return the column number of the offset. The
+column number of an offset is the number of objects between it
+and the preceding newline, or between it and the beginning of the
+buffer if the offset is on the first line of the buffer."))
 
 (defmethod buffer-column-number ((buffer standard-buffer) (offset integer))
   (loop for i downfrom offset
@@ -412,16 +444,17 @@
 	count t))
 
 (defgeneric line-number (mark)
-  (:documentation "Return the line number of the mark.  Lines are numbered from zero."))
+  (:documentation "Return the line number of the mark.  Lines are
+numbered from zero."))
 
 (defmethod line-number ((mark mark-mixin))
   (buffer-line-number (buffer mark) (offset mark)))
 
 (defgeneric column-number (mark)
-  (:documentation "Return the column number of the mark. The column number of a mark is
- the number of objects between it and the preceding newline, or
- between it and the beginning of the buffer if the mark is on the
- first line of the buffer."))
+  (:documentation "Return the column number of the mark. The
+column number of a mark is the number of objects between it and
+the preceding newline, or between it and the beginning of the
+buffer if the mark is on the first line of the buffer."))
 
 (defmethod column-number ((mark mark-mixin))
   (buffer-column-number (buffer mark) (offset mark)))
@@ -440,10 +473,11 @@
        finally (return (column-number mark))))
 
 (defgeneric insert-buffer-object (buffer offset object)
-  (:documentation "Insert the object at the offset in the buffer.  Any left-sticky marks
- that are placed at the offset will remain positioned before the
- inserted object.  Any right-sticky marks that are placed at the
- offset will be positioned after the inserted object."))
+  (:documentation "Insert the object at the offset in the buffer.
+Any left-sticky marks that are placed at the offset will remain
+positioned before the inserted object.  Any right-sticky marks
+that are placed at the offset will be positioned after the
+inserted object."))
 
 (defmethod insert-buffer-object ((buffer standard-buffer) offset object)
   (assert (<= 0 offset) ()
@@ -453,31 +487,33 @@
   (insert* (slot-value buffer 'contents) offset object))
 
 (defgeneric insert-buffer-sequence (buffer offset sequence)
-  (:documentation "Like calling insert-buffer-object on each of the objects in the
-sequence."))
+  (:documentation "Like calling insert-buffer-object on each of
+the objects in the sequence."))
       
 (defmethod insert-buffer-sequence ((buffer standard-buffer) offset sequence)
   (insert-vector* (slot-value buffer 'contents) offset sequence))
 
 (defgeneric insert-object (mark object)
-  (:documentation "Insert the object at the mark.  This function simply calls
-insert-buffer-object with the buffer and the position of the mark."))
+  (:documentation "Insert the object at the mark.  This function
+simply calls insert-buffer-object with the buffer and the
+position of the mark."))
 
 (defmethod insert-object ((mark mark-mixin) object)
   (insert-buffer-object (buffer mark) (offset mark) object))
 
 (defgeneric insert-sequence (mark sequence)
-  (:documentation "Insert the objects in the sequence at the mark. This function simply
-calls insert-buffer-sequence with the buffer and the position of the
-mark."))
+  (:documentation "Insert the objects in the sequence at the
+mark. This function simply calls insert-buffer-sequence with the
+buffer and the position of the mark."))
 
 (defmethod insert-sequence ((mark mark-mixin) sequence)
   (insert-buffer-sequence (buffer mark) (offset mark) sequence))
 
 (defgeneric delete-buffer-range (buffer offset n)
-  (:documentation "Delete n objects from the buffer starting at the offset.  If offset
- is negative or offset+n is greater than the size of the buffer, a
- no-such-offset condition is signaled."))
+  (:documentation "Delete n objects from the buffer starting at
+the offset.  If `offset' is negative or `offset'+`n' is greater
+than the size of the buffer, a `no-such-offset' condition is
+signaled."))
 
 (defmethod delete-buffer-range ((buffer standard-buffer) offset n)
   (assert (<= 0 offset) ()
@@ -488,9 +524,9 @@
 	do (delete* (slot-value buffer 'contents) offset)))
 
 (defgeneric delete-range (mark &optional n)
-  (:documentation "Delete n objects after (if n > 0) or before (if n < 0) the mark.
-This function eventually calls delete-buffer-range, provided that n
-is not zero."))
+  (:documentation "Delete `n' objects after `(if n > 0)' or
+before `(if n < 0)' the mark.  This function eventually calls
+delete-buffer-range, provided that `n' is not zero."))
 
 (defmethod delete-range ((mark mark-mixin) &optional (n 1))
   (cond ((plusp n) (delete-buffer-range (buffer mark) (offset mark) n))
@@ -499,9 +535,10 @@
 
 (defgeneric delete-region (mark1 mark2)
   (:documentation "Delete the objects in the buffer that are
-between mark1 and mark2.  An error is signaled if the two marks
-are positioned in different buffers.  It is acceptable to pass an
-offset in place of one of the marks."))
+between `mark1' and `mark2'.  An error is signaled if the two
+marks are positioned in different buffers.  It is acceptable to
+pass an offset in place of one of the marks. This function calls
+`delete-buffer-range' with the appropriate arguments."))
 
 (defmethod delete-region ((mark1 mark-mixin) (mark2 mark-mixin))
   (assert (eq (buffer mark1) (buffer mark2)))
@@ -524,9 +561,10 @@
     (delete-buffer-range (buffer mark2) offset1 (- offset2 offset1))))
 
 (defgeneric buffer-object (buffer offset)

[103 lines skipped]