"H. Tunc Simsek" <······@EECS.Berkeley.Edu> writes:
> How do we document a method in CMUCL.
>
> A function is documented:
>
> (defun foo ()
> "document"
> (values))
>
> How do we do it for (defmethod ...)
You can document the _method_ the same way you document the function,
i.e.:
(defmethod foo ()
"document"
(values))
But since methods aren't really visible to users, this won't get you
far. So what you probably want to document is not the method, but the
generic function the method belongs to. To do this, you have to use
defgeneric and it's :documentation parameter:
(defgeneric foo ()
(:documentation "document"))
Regs, Pierre.
--
Pierre Mai <····@acm.org> PGP and GPG keys at your nearest Keyserver
"One smaller motivation which, in part, stems from altruism is Microsoft-
bashing." [Microsoft memo, see http://www.opensource.org/halloween1.html]
····@acm.org (Pierre R. Mai) writes:
> "H. Tunc Simsek" <······@EECS.Berkeley.Edu> writes:
>
> > How do we document a method in CMUCL.
> >
> > A function is documented:
> >
> > (defun foo ()
> > "document"
> > (values))
> >
> > How do we do it for (defmethod ...)
>
> You can document the _method_ the same way you document the function,
> i.e.:
>
> (defmethod foo ()
> "document"
> (values))
>
> But since methods aren't really visible to users, this won't get you
> far. So what you probably want to document is not the method, but the
> generic function the method belongs to. To do this, you have to use
> defgeneric and it's :documentation parameter:
>
> (defgeneric foo ()
> (:documentation "document"))
This is correct, but unhelpful (not in the sense of Pierre being
unhelpful). In theory you should be able to do
(defmethod zut ((x integer) (s symbol))
"I am a method of ZUT"
(list x s))
(documentation (find-method #'zut
'()
(mapcar #'find-class '(integer symbol)))
t)
In LW this works fine. In CMUCL this returns NIL (I suppose because I
have some 'dont-save-doc-strings' setting around).
Having said so, I must say that this interface is very cumbersome to
use. This is where the "unhelpful" adjective (as referred to CL)
comes to mind.
Cheers
--
Marco Antoniotti ===========================================
PARADES, Via San Pantaleo 66, I-00186 Rome, ITALY
tel. +39 - 06 68 10 03 17, fax. +39 - 06 68 80 79 26
http://www.parades.rm.cnr.it/~marcoxa
Yes, this is not useful. Would there be a hack so that we could
access it say using a new function:
(help 'zut)
So HELP would do a heavy computation to figure out what ZUT is
and then provide its documentation.
Tunc
Marco Antoniotti wrote:
> This is correct, but unhelpful (not in the sense of Pierre being
> unhelpful). In theory you should be able to do
>
> (defmethod zut ((x integer) (s symbol))
> "I am a method of ZUT"
> (list x s))
>
> (documentation (find-method #'zut
> '()
> (mapcar #'find-class '(integer symbol)))
> t)
>
> In LW this works fine. In CMUCL this returns NIL (I suppose because I
> have some 'dont-save-doc-strings' setting around).
>
> Having said so, I must say that this interface is very cumbersome to
> use. This is where the "unhelpful" adjective (as referred to CL)
> comes to mind.
>
> Cheers
>
> --
> Marco Antoniotti ===========================================
> PARADES, Via San Pantaleo 66, I-00186 Rome, ITALY
> tel. +39 - 06 68 10 03 17, fax. +39 - 06 68 80 79 26
> http://www.parades.rm.cnr.it/~marcoxa
"H. Tunc Simsek" <······@EECS.Berkeley.Edu> writes:
> Yes, this is not useful. Would there be a hack so that we could
> access it say using a new function:
>
> (help 'zut)
>
> So HELP would do a heavy computation to figure out what ZUT is
> and then provide its documentation.
What exactly should (help 'my-fun) deliver in the following example?
(defgeneric my-fun (a b)
(:documentation "Frob a using b."))
(defmethod my-fun ((a integer) (b integer))
"This frobs an integer using an integer."
(ash a b))
(defmethod my-fun (a b)
"We don't know how to frob anything else at the moment."
(error "Don't know how to frob ~S using ~S. Contact your local Wizard."
a b))
(help 'my-fun)
=> ???
(This is ignoring for the moment the problem that you could also have
variables, types, etc. with the same name, which is why documentation
takes it's second parameter)
As far as I understand you have a problem with the advice of using
documentation strings on generic functions and not on methods, or of
specifiying which method to use. But either you let help return a
list of entities and their corresponding documentation strings, or you
have to tell help which entity with a given name you mean. In the
case of methods you would have to specify which method of a given GF
you mean.
There is a n:1 mapping between methods and GFs (and GF names), and no
matter what you do, you can't change that fact. So anything you come
up with, you either have to provide more information to the function,
or you have to live with an evil hack. That being said, here are some
possible courses of action (not all mutually exclusive):
1) Give up on defmethod doc-strings (which I find rarely useful, since
doc-strings should document interfaces IMHO, which are logically
represented by the GF and not it's implementations), and document
generic functions instead, as I suggested. Then you can use
documentation and all the nice editors (like Emacs using ILISP or
ELI) to get at the documentation.
2) Write a macro-wrapper for defmethod, that put's the method's
documentation string into the documentation of the generic function
(possibly only if the GF isn't already documented). This is an
evil hack, since there are n methods for every GF, so which doc
string should "win"?
3) Write a help function that is given more information to locate the
correct entity and deliver it's doc-string, something like
(defgeneric help (name type &rest specs)
(:documentation
"Gives the documentation for the entity that is specified by the
given 'type' (i.e. like in cl:documentation) and possibly
further parameters to specify which entity is intended, like
e.g. (help 'my-fun 'method :arguments (1 2)) would return the
docstring of the first applicable primary method for a call
with the given parameters 1 and 2."))
4) Write a help function that returns all possible doc-strings
together with the entities.
5) Respecify your problem so that maybe other solutions come to
mind...
Regs, Pierre.
--
Pierre Mai <····@acm.org> PGP and GPG keys at your nearest Keyserver
"One smaller motivation which, in part, stems from altruism is Microsoft-
bashing." [Microsoft memo, see http://www.opensource.org/halloween1.html]
I think your suggestion #4 is the most reasonable. Except I wouldn't
go for all entities, instead just the most used ones:
functions, generic functions, methods, classes, structures and
variables.
I believe there is a package CLLIB from Sam Steingold that has such a
function (ALL-DOCS).
Except that it doesn't handle generic functions, and methods.
Tunc
"Pierre R. Mai" wrote:
>
> "H. Tunc Simsek" <······@EECS.Berkeley.Edu> writes:
>
> > Yes, this is not useful. Would there be a hack so that we could
> > access it say using a new function:
> >
> > (help 'zut)
> >
> > So HELP would do a heavy computation to figure out what ZUT is
> > and then provide its documentation.
>
> What exactly should (help 'my-fun) deliver in the following example?
>
> (defgeneric my-fun (a b)
> (:documentation "Frob a using b."))
>
> (defmethod my-fun ((a integer) (b integer))
> "This frobs an integer using an integer."
> (ash a b))
>
> (defmethod my-fun (a b)
> "We don't know how to frob anything else at the moment."
> (error "Don't know how to frob ~S using ~S. Contact your local Wizard."
> a b))
>
> (help 'my-fun)
>
> => ???
>
> (This is ignoring for the moment the problem that you could also have
> variables, types, etc. with the same name, which is why documentation
> takes it's second parameter)
>
> As far as I understand you have a problem with the advice of using
> documentation strings on generic functions and not on methods, or of
> specifiying which method to use. But either you let help return a
> list of entities and their corresponding documentation strings, or you
> have to tell help which entity with a given name you mean. In the
> case of methods you would have to specify which method of a given GF
> you mean.
>
> There is a n:1 mapping between methods and GFs (and GF names), and no
> matter what you do, you can't change that fact. So anything you come
> up with, you either have to provide more information to the function,
> or you have to live with an evil hack. That being said, here are some
> possible courses of action (not all mutually exclusive):
>
> 1) Give up on defmethod doc-strings (which I find rarely useful, since
> doc-strings should document interfaces IMHO, which are logically
> represented by the GF and not it's implementations), and document
> generic functions instead, as I suggested. Then you can use
> documentation and all the nice editors (like Emacs using ILISP or
> ELI) to get at the documentation.
>
> 2) Write a macro-wrapper for defmethod, that put's the method's
> documentation string into the documentation of the generic function
> (possibly only if the GF isn't already documented). This is an
> evil hack, since there are n methods for every GF, so which doc
> string should "win"?
>
> 3) Write a help function that is given more information to locate the
> correct entity and deliver it's doc-string, something like
>
> (defgeneric help (name type &rest specs)
> (:documentation
> "Gives the documentation for the entity that is specified by the
> given 'type' (i.e. like in cl:documentation) and possibly
> further parameters to specify which entity is intended, like
> e.g. (help 'my-fun 'method :arguments (1 2)) would return the
> docstring of the first applicable primary method for a call
> with the given parameters 1 and 2."))
>
> 4) Write a help function that returns all possible doc-strings
> together with the entities.
>
> 5) Respecify your problem so that maybe other solutions come to
> mind...
>
> Regs, Pierre.
>
> --
> Pierre Mai <····@acm.org> PGP and GPG keys at your nearest Keyserver
> "One smaller motivation which, in part, stems from altruism is Microsoft-
> bashing." [Microsoft memo, see http://www.opensource.org/halloween1.html]
Pierre R. Mai wrote:
> What exactly should (help 'my-fun) deliver in the following example?
>
> (defgeneric my-fun (a b)
> (:documentation "Frob a using b."))
>
> (defmethod my-fun ((a integer) (b integer))
> "This frobs an integer using an integer."
> (ash a b))
>
> (defmethod my-fun (a b)
> "We don't know how to frob anything else at the moment."
> (error "Don't know how to frob ~S using ~S. Contact your local Wizard."
> a b))
>
> (help 'my-fun)
>
> => ???
It should display, or return in some fashion, all three
documentation strings. Just like DESCRIBE does in CMU CL
and ACL and probably most other implementations. (Which
suggests the question "What exactly was the point of the
mooted HELP function, again?".)
As for the question about documentation strings for methods,
if
(documentation (find-method #'my-fun
nil
(mapcar #'find-class '(integer integer)))
t)
doesn't appeal -- and I entirely understand why it doesn't --
then why not write a function that gives a more appealing
interface to the same functionality?
(defun method-documentation (name specializers
&optional (qualifiers nil))
(documentation (find-method (symbol-function name)
qualifiers
(mapcar #'find-class specializers))
t))
(method-documentation 'my-fun '(integer integer))
==> "This frobs an integer using an integer."
It's a pity you can't write
(defmethod documentation ((s symbol) (doc-type (cons (eql method) t)))
[etc])
:-)
--
Gareth McCaughan ················@pobox.com
sig under construction
Gareth McCaughan wrote:
>
> Pierre R. Mai wrote:
>
> > What exactly should (help 'my-fun) deliver in the following example?
> >
> > (defgeneric my-fun (a b)
> > (:documentation "Frob a using b."))
> >
> > (defmethod my-fun ((a integer) (b integer))
> > "This frobs an integer using an integer."
> > (ash a b))
> >
> > (defmethod my-fun (a b)
> > "We don't know how to frob anything else at the moment."
> > (error "Don't know how to frob ~S using ~S. Contact your local Wizard."
> > a b))
> >
> > (help 'my-fun)
> >
> > => ???
>
> It should display, or return in some fashion, all three
> documentation strings. Just like DESCRIBE does in CMU CL
> and ACL and probably most other implementations. (Which
> suggests the question "What exactly was the point of the
> mooted HELP function, again?".)
I understand that I may be looking for something in btwn. DOCUMENTATION
and DESCRIBE. But describe is simply too rich.
In your example I think what would be nice to see is:
(help 'my-fun)
=> MY-FUN [GENERIC-FUNCTION]
args: A B
Frob A using B.
Methods:
--------
MY-FUN
args: (A INTEGER) (B INTEGER)
This frobs an integer using an integer.
MY-FUN
args: A B
We don't know how to frob anything else at the moment.
Or something in a similar fashion.
Tunc
>
> As for the question about documentation strings for methods,
> if
>
> (documentation (find-method #'my-fun
> nil
> (mapcar #'find-class '(integer integer)))
> t)
>
> doesn't appeal -- and I entirely understand why it doesn't --
> then why not write a function that gives a more appealing
> interface to the same functionality?
>
> (defun method-documentation (name specializers
> &optional (qualifiers nil))
> (documentation (find-method (symbol-function name)
> qualifiers
> (mapcar #'find-class specializers))
> t))
>
> (method-documentation 'my-fun '(integer integer))
> ==> "This frobs an integer using an integer."
>
> It's a pity you can't write
>
> (defmethod documentation ((s symbol) (doc-type (cons (eql method) t)))
> [etc])
>
> :-)
>
> --
> Gareth McCaughan ················@pobox.com
> sig under construction
Gareth McCaughan <················@pobox.com> writes:
> Pierre R. Mai wrote:
>
> > What exactly should (help 'my-fun) deliver in the following example?
> >
> > (defgeneric my-fun (a b)
> > (:documentation "Frob a using b."))
> >
> > (defmethod my-fun ((a integer) (b integer))
> > "This frobs an integer using an integer."
> > (ash a b))
> >
> > (defmethod my-fun (a b)
> > "We don't know how to frob anything else at the moment."
> > (error "Don't know how to frob ~S using ~S. Contact your local Wizard."
> > a b))
> >
> > (help 'my-fun)
> >
> > => ???
>
> It should display, or return in some fashion, all three
> documentation strings. Just like DESCRIBE does in CMU CL
> and ACL and probably most other implementations. (Which
> suggests the question "What exactly was the point of the
> mooted HELP function, again?".)
>
> As for the question about documentation strings for methods,
> if
>
> (documentation (find-method #'my-fun
> nil
> (mapcar #'find-class '(integer integer)))
> t)
>
> doesn't appeal -- and I entirely understand why it doesn't --
> then why not write a function that gives a more appealing
> interface to the same functionality?
>
> (defun method-documentation (name specializers
> &optional (qualifiers nil))
> (documentation (find-method (symbol-function name)
> qualifiers
> (mapcar #'find-class specializers))
> t))
>
> (method-documentation 'my-fun '(integer integer))
> ==> "This frobs an integer using an integer."
>
> It's a pity you can't write
>
> (defmethod documentation ((s symbol) (doc-type (cons (eql method) t)))
> [etc])
Well, yes. But I believe I can improve on your solution a bit
Let's think about what DOCUMENTATION wants. It wants an 'object' and
an "extra specifier".
So here you have it.
(defstruct method-spec fun qualifiers specialized-arglist)
(defun method-specifier (fun qualifiers specialized-arglist)
(make-method-spec :fun fun
:qualifiers qualifiers
:specialized-arglist (mapcar #'find-class specialized-arglist)))
(defmethod documentation ((gf standard-generic-function) (ms method-spec))
(documentation (find-method gf
(method-spec-qualifiers ms)
(method-spec-specialized-arglist ms))
t))
Of course you can decide to remove the 'fun' slot or change other
things. Anyway, the net result is that now you have a way of saying
(defmethod popeye ((p pipe) (s spinach))
"I am the method, the method I am."
(smoke p)
(eat s))
(documentation #'popeye (method-specifier #'popeye () '(pipe spinach)))
Cheers
--
Marco Antoniotti ===========================================
PARADES, Via San Pantaleo 66, I-00186 Rome, ITALY
tel. +39 - 06 68 10 03 17, fax. +39 - 06 68 80 79 26
http://www.parades.rm.cnr.it/~marcoxa
In article <··············@copernico.parades.rm.cnr.it>, Marco Antoniotti <·······@copernico.parades.rm.cnr.it> wrote:
> This is correct, but unhelpful (not in the sense of Pierre being
> unhelpful). In theory you should be able to do
>
> (defmethod zut ((x integer) (s symbol))
> "I am a method of ZUT"
> (list x s))
>
> (documentation (find-method #'zut
> '()
> (mapcar #'find-class '(integer symbol)))
> t)
>
>
> In LW this works fine.
Same in MCL.
> Having said so, I must say that this interface is very cumbersome to
> use. This is where the "unhelpful" adjective (as referred to CL)
> comes to mind.
Hmm, having a development environment should give you
easy access to this stuff. In MCL I'd just start by
inspecting the generic function and move from there
to the methods. You can cut/copy and paste Lisp objects (not just as text!!)
in MCL. Also, the variable @ gives you the last cut or copied
object. You also can imagine what (top-inspect-form) does. ;-)
Thus moving around in datastructures (in this case functions, generic functions,
symbols, methods and method functions) and get a handle on them is easy.