·······@stsci.edu (John M. Adams) writes:
> Defclass forms tend not to be very pretty. Among other things,
> substantial docstrings are awkward.
>
> The best I've generally been able to do is to start the string on a
> newline and apply fill-region-as-paragraph after writing
> :documentation so as to get something like this:
>
> (defcosi-class cos-wavecal-acq (cos-science-exposure cos-abstract-acq) ()
> (:documentation
> "Here we classify acq/image and acq/peakxd. At the commanding level,
> these are two distinct activities each of which include an initial
> wavecal. The initial wavecal is hidden from trans. This gives a
> wrinkle in calculating apertime. Moreover, two qaposition records are
> required."))
>
> I've looked at various code related to this including cl-indent and,
> more relevantly in my case, fi-indent.el. This is hairy enough to
> discourage casual hacking.
This sounds like an Emacs question.
>
> Can anyone say: "My defclass forms are really pretty and this is
> how..."?
All in all, I must say that the only real problem I have is similar to
yours. Long documentation strings are not pretty in Common Lisp. The
main problem is that they defy conventional indentation rules,
i.e. you can indent them as you did, but then you are not guaranteed
that the result of DOCUMENTATION is pretty. If you ask for the
DOCUMENTATION of COS-WAVECAL-ACQ you will get something like:
"Here we classify acq/image and acq/peakxd. At the commanding level,
these are two distinct activities each of which include an initial
wavecal. The initial wavecal is hidden from trans. This gives a
wrinkle in calculating apertime. Moreover, two qaposition records are
required."
I have no solution for this. And I think there is no solution. unless
the standard is changed to say that implementations are allowed
(mandated) to remove extra spacing after a newline in a doc string.
My only suggestion is to follow Emacs doc string rules. The first
line of the doc string should be a short and self contained
description of the definition. The full description should come in the
next lines.
Apart from that, I think DEFCLASS forms are ok, AFAIAC.
Cheers
--
Marco Antoniotti ========================================================
NYU Courant Bioinformatics Group tel. +1 - 212 - 998 3488
719 Broadway 12th Floor fax +1 - 212 - 995 4122
New York, NY 10003, USA http://bioinformatics.cat.nyu.edu
"Hello New York! We'll do what we can!"
Bill Murray in `Ghostbusters'.
Marco Antoniotti <·······@cs.nyu.edu> writes:
> All in all, I must say that the only real problem I have is similar to
> yours. Long documentation strings are not pretty in Common Lisp.
As an aside, I tried at some time in the past to get multiple doc
strings to be accepted as a synonym for their line-broken
concatenations, so that
(defun foo (x y)
"This function adds"
"the variable x to"
"the variable y."
(+ x y))
would be taken as a synonym for
(defun foo (x y)
"This function adds
the variable x to"
the variable y."
(+ x y))
I guess it goes without saying that I did not succeed.
> The main problem is that they defy conventional indentation rules,
But then, the problem is today ameliorated slightly by the fact that there
is no attached semantics to the text data you store here. Often, when I
use them at all (which isn't much), I put HTML markup in these now.
So...
(defun foo (x y)
"This function adds<br />
the variable x to<br />
the variable y."
(+ x y))
if I want a multi-line doc string, or
(defun foo (x y)
"This function adds
the variable x to
the variable y."
(+ x y))
if I don't.
> i.e. you can indent them as you did, but then you are not guaranteed
> that the result of DOCUMENTATION is pretty. If you ask for the
> DOCUMENTATION of COS-WAVECAL-ACQ you will get something like:
>
> "Here we classify acq/image and acq/peakxd. At the commanding level,
> these are two distinct activities each of which include an initial
> wavecal. The initial wavecal is hidden from trans. This gives a
> wrinkle in calculating apertime. Moreover, two qaposition records are
> required."
>
> I have no solution for this. And I think there is no solution. unless
> the standard is changed to say that implementations are allowed
> (mandated) to remove extra spacing after a newline in a doc string.
>
> My only suggestion is to follow Emacs doc string rules. The first
> line of the doc string should be a short and self contained
> description of the definition. The full description should come in the
> next lines.
As alternate solutions go, this one isn't terrible. But it
underscores my point--that the semantics of the text are open to
interpretation.
I've also seen things like #"..." defined as #.(format nil "..."),
so that you could write:
#"foo ·@
bar ·@
baz"
So there's another alternative. The world is full of them if you look
hard enough...
Then again, the world is also full of more compelling problems. For things
like this, I mostly work backward from the other end: if I have a system
that needs the data, how do I provide it with the data it needs. If I don't
have a system that needs the data, who cares how it looks or whether it's
even there?