-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi, I stumbled upon this as I played with the SLIME inspector: some
objects supplied documentation with them, some didn't and now I'm
trying to understand the different handling of documentation along
the types of things one can define -- that would be structures,
CLOS classes and (generic) functions.
(Eventually this whole thing may be implementation dependent
(SBCL here) but that would be an anwser, too.)
I was in every case expecting to get the supplied string in some way.
Now, just to reason about what I thought was happening in the numbered
cases, since in the other cases everything is fine with me:
1,2 The object, which is the class FOO, has no documentation, since
DEFSTRUCT defines a new type and uses the string for that
purpose; since CLOS came later (?) it's not integrated with FOO
being a CLOS class instance (um, just speculating, really).
3,4 Since INSPECT has the slot I suspect that describe just doesn't
handle CLOS documentation? However it's odd that other
information about the CLOS internals are present when
(describe 'BAR) runs ...
5 Function objects just don't save that kind of information?
Also, the hyperspec says something about INSPECT being
the interactive version of DESCRIBE, which is odd given the different
of amount information both versions supply (even if its implementation
dependent).
So, I can rely on DOCUMENTATION in all cases except LAMBDA-build
closures/functions, which is good.
I would appreciate it if you could just review and correct my thoughts
about this. It's certainly not vitally important though :)
Best regards,
Olof
- --snip--
(defstruct foo
"This is structure class FOO."
someslot)
; (documentation (find-class 'FOO) T) => This is ...
; (describe 'FOO) => Type documentation: This is ...
; (describe (find-class 'FOO)) => Its proper name is FOO. <- 1
; (inspect (find-class 'FOO)) => %DOCUMENTATION: NIL <- 2
(defclass bar ()
()
(:documentation "This is class BAR."))
; (documentation (find-class 'bar) T) => This is ...
; (describe 'BAR) => #<STANDARD-CLASS BAR> <- 3
; (describe (find-class 'BAR)) => #<STANDARD-CLASS BAR> <- 4
; (inspect (find-class 'BAR)) => %DOCUMENTATION: This is ...
(defgeneric baz (x)
(:documentation "This is generic function BAZ."))
; (documentation (function baz) T) => This is generic function BAZ.
; (describe 'baz) => Its documentation is: This is ...
; ^ same for (function baz)
; (inspect (function baz)) => %DOCUMENTATION: This is ...
(defun qux ()
"This is function QUX."
42)
; (documentation (function qux) T) => This is function QUX.
; (describe 'qux) => Function documentation: This is ...
; ^ same for (function qux)
; (inspect (function qux)) => The object is a FUNCTION named QUX. <- 5
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.9 (GNU/Linux)
iEYEARECAAYFAkjlbzgACgkQEiTh585nXwA9FgCcDTG6V8EA6dEcSOTJtNuD+tZ9
wKkAn1YDbe+y1mXlY8HHRl2eTzlTB7TB
=++Hk
-----END PGP SIGNATURE-----
Olof-Joachim Frahm wrote:
>
> Hi, I stumbled upon this as I played with the SLIME inspector: some
> objects supplied documentation with them, some didn't and now I'm
> trying to understand the different handling of documentation along
> the types of things one can define -- that would be structures,
> CLOS classes and (generic) functions.
The CLHS is a much better source of info then playing around at the
repl.
>
> (Eventually this whole thing may be implementation dependent
> (SBCL here) but that would be an anwser, too.)
" Documentation strings are made available for debugging purposes.
Conforming programs are permitted to use documentation strings when
they are present, but should not depend for their correct behavior on
the presence of those documentation strings . An implementation is
permitted to discard documentation strings at any time for
implementation-defined reasons."
Cheers,
drewc
> I was in every case expecting to get the supplied string in some way.
> Now, just to reason about what I thought was happening in the numbered
> cases, since in the other cases everything is fine with me:
>
> 1,2 The object, which is the class FOO, has no documentation, since
> DEFSTRUCT defines a new type and uses the string for that
> purpose; since CLOS came later (?) it's not integrated with FOO
> being a CLOS class instance (um, just speculating, really).
>
> 3,4 Since INSPECT has the slot I suspect that describe just doesn't
> handle CLOS documentation? However it's odd that other
> information about the CLOS internals are present when
> (describe 'BAR) runs ...
>
> 5 Function objects just don't save that kind of information?
>
> Also, the hyperspec says something about INSPECT being
> the interactive version of DESCRIBE, which is odd given the different
> of amount information both versions supply (even if its implementation
> dependent).
>
> So, I can rely on DOCUMENTATION in all cases except LAMBDA-build
> closures/functions, which is good.
>
> I would appreciate it if you could just review and correct my thoughts
> about this. It's certainly not vitally important though :)
>
> Best regards,
> Olof
>
> - --snip--
>
> (defstruct foo
> "This is structure class FOO."
> someslot)
>
> ; (documentation (find-class 'FOO) T) => This is ...
> ; (describe 'FOO) => Type documentation: This is ...
> ; (describe (find-class 'FOO)) => Its proper name is FOO. <- 1
> ; (inspect (find-class 'FOO)) => %DOCUMENTATION: NIL <- 2
>
> (defclass bar ()
> ()
> (:documentation "This is class BAR."))
>
> ; (documentation (find-class 'bar) T) => This is ...
> ; (describe 'BAR) => #<STANDARD-CLASS BAR> <- 3
> ; (describe (find-class 'BAR)) => #<STANDARD-CLASS BAR> <- 4
> ; (inspect (find-class 'BAR)) => %DOCUMENTATION: This is ...
>
> (defgeneric baz (x)
> (:documentation "This is generic function BAZ."))
>
> ; (documentation (function baz) T) => This is generic function BAZ.
> ; (describe 'baz) => Its documentation is: This is ...
> ; ^ same for (function baz)
> ; (inspect (function baz)) => %DOCUMENTATION: This is ...
>
> (defun qux ()
> "This is function QUX."
> 42)
>
> ; (documentation (function qux) T) => This is function QUX.
> ; (describe 'qux) => Function documentation: This is ...
> ; ^ same for (function qux)
> ; (inspect (function qux)) => The object is a FUNCTION named QUX. <- 5
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.9 (GNU/Linux)
>
> iEYEARECAAYFAkjlbzgACgkQEiTh585nXwA9FgCcDTG6V8EA6dEcSOTJtNuD+tZ9
> wKkAn1YDbe+y1mXlY8HHRl2eTzlTB7TB
> =++Hk
> -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 2008-10-07, Drew Crampsie <·············@gmail.com> wrote:
> Olof-Joachim Frahm wrote:
>>
>> Hi, I stumbled upon this as I played with the SLIME inspector: some
>> objects supplied documentation with them, some didn't and now I'm
>> trying to understand the different handling of documentation along
>> the types of things one can define -- that would be structures,
>> CLOS classes and (generic) functions.
>
> The CLHS is a much better source of info then playing around at the
> repl.
Thanks for your anwser. I think that means I have to change my
approach a bit :)
Regards,
Olof
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.9 (GNU/Linux)
iEYEARECAAYFAkjvPkUACgkQEiTh585nXwBqVgCfTW4s/Er/J+xfiB5vbgOOit9I
zm8An3VGT8CpwMj6qozBPlZIAtWU4LAK
=Dj2R
-----END PGP SIGNATURE-----
On Fri, 2008-10-10 at 11:35 +0000, Olof-Joachim Frahm wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 2008-10-07, Drew Crampsie <·············@gmail.com> wrote:
> > Olof-Joachim Frahm wrote:
> >>
> >> Hi, I stumbled upon this as I played with the SLIME inspector: some
> >> objects supplied documentation with them, some didn't and now I'm
> >> trying to understand the different handling of documentation along
> >> the types of things one can define -- that would be structures,
> >> CLOS classes and (generic) functions.
> >
> > The CLHS is a much better source of info then playing around at the
> > repl.
>
> Thanks for your anwser. I think that means I have to change my
> approach a bit :)
>
> Regards,
> Olof
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.9 (GNU/Linux)
>
> iEYEARECAAYFAkjvPkUACgkQEiTh585nXwBqVgCfTW4s/Er/J+xfiB5vbgOOit9I
> zm8An3VGT8CpwMj6qozBPlZIAtWU4LAK
> =Dj2R
> -----END PGP SIGNATURE-----
Slime has a slime-hyperspec-lookup thingy. You can bind it to a
shortcut-key if you want:
(define-key slime-mode-map [f1] 'slime-hyperspec-lookup)
..and assign a local path or some url to common-lisp-hyperspec-root.
http://common-lisp.net/project/slime/doc/html/Documentation.html
--
Lars Rune Nøstdal || AJAX/Comet GUI type stuff for Common Lisp
http://nostdal.org/ || http://groups.google.com/group/symbolicweb