From: Nikodemus S. <tsi...@cc...> - 2004-07-22 14:16:54
Attachments:
socket-doc.patch
|
I did a quick conversion of SB-BSD-SOCKETS documentation into TexInfo, with the results visible in here: http://www.niksula.cs.hut.fi/~tsiivola/tmp/sbcl.pdf The attached patch makes this happen. Opinions one the conversion, and mergability of this would be welcome. Cheers, -- Nikodemus "Not as clumsy or random as a C++ or Java. An elegant weapon for a more civilized time." |
From: Christophe R. <cs...@ca...> - 2004-07-22 15:03:47
|
Nikodemus Siivola <tsi...@cc...> writes: > + (:documentation "Slots: NAME, ALIASES, ADDRESS-TYPE, ADDRESSES.")) > + (:documentation "Common base class of all sockets. Slots: > +FILE-DESCRIPTOR, FAMILY, PROTOCOL, TYPE, STREAM."))) Simply printing the symbol-names of slots is almost useless to the user: to use a slot name, the package must also be known. In any case, I would guess that the preferred interface is not SLOT-VALUE but rather some accessor. In addition, this way of working is very fragile: it's certainly not OAOO. Maybe the document string extractor should be taught about slot descriptions in classes, check for exported accessor names, and document those? Cheers, Christophe -- http://www-jcsu.jesus.cam.ac.uk/~csr21/ +44 1223 510 299/+44 7729 383 757 (set-pprint-dispatch 'number (lambda (s o) (declare (special b)) (format s b))) (defvar b "~&Just another Lisp hacker~%") (pprint #36rJesusCollegeCambridge) |
From: Nikodemus S. <tsi...@cc...> - 2004-07-22 15:54:22
|
On Thu, 22 Jul 2004, Christophe Rhodes wrote: >> + (:documentation "Slots: NAME, ALIASES, ADDRESS-TYPE, ADDRESSES.")) >> + (:documentation "Common base class of all sockets. Slots: >> +FILE-DESCRIPTOR, FAMILY, PROTOCOL, TYPE, STREAM."))) > > Simply printing the symbol-names of slots is almost useless to the user: to > use a slot name, the package must also be known. In any case, I would > guess that the preferred interface is not SLOT-VALUE but rather some > accessor. Probably quite true. > In addition, this way of working is very fragile: it's certainly not > OAOO. Maybe the document string extractor should be taught about slot > descriptions in classes, check for exported accessor names, and > document those? Sounds sane, how about something along the lines of: (defclass foo (bar) ((quux :initarg :quux :initform *quux* :accessor get-quux :documentation "Frobbed quux representing the baz.") (baz :initarg :baz :initform *baz* :reader get-baz :allocation :class :documentation "Instance baz.") (xyzzy))) producing something like: FOO [Class] Class precendece list: FOO BAR STANDARD-OBJECT T Slots: quux Initarg: :quux Frobbed quux representing the baz. baz (class-allocation) Initarg: :baz Instance baz. GET-QUUX bar [Accessor] (SETF GET-QUUX) new-quux bar [Accessor] Frobbed quux representing the baz. GET-BAZ bar [Accessor] Instance baz. Cheers, -- Nikodemus "Not as clumsy or random as a C++ or Java. An elegant weapon for a more civilized time." |
From: Nikodemus S. <tsi...@cc...> - 2004-07-23 12:12:16
Attachments:
socket-doc.patch
|
Latest take. ...not actively planning to merge this before 0.8.13, though. http://www.random-state.net/tmp/sbcl.pdf Changes: * Revert to similar structure used in the html docs. * Smarter class documentation (class precendence lists, and initargs of documented slots). * Adjust the documentation to take advantage of the above. Cheers, -- Nikodemus "Not as clumsy or random as a C++ or Java. An elegant weapon for a more civilized time." |