I wonder what is the "proper" way to handle indentations and
linebreaks in documentation strings. If I just keep typing and press
C-Q, SLIME will indent it like this:
(defun foo (x)
"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat."
(1+ x))
Then (describe 'foo) gives:
Function documentation:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.
It is OK for the function documentation to start with a 2-space
indentation, and none after that?
Thanks,
Tamas
From: Kent M Pitman
Subject: Re: indenting the documentation string
Date:
Message-ID: <uk5t9bvtb.fsf@nhplace.com>
Tamas Papp <······@gmail.com> writes:
> I wonder what is the "proper" way to handle indentations and
> linebreaks in documentation strings. If I just keep typing and press
> C-Q, SLIME will indent it like this:
>
> (defun foo (x)
> "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
> do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
> enim ad minim veniam, quis nostrud exercitation ullamco laboris
> nisi ut aliquip ex ea commodo consequat."
> (1+ x))
>
> Then (describe 'foo) gives:
>
> Function documentation:
> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
> do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
> enim ad minim veniam, quis nostrud exercitation ullamco laboris
> nisi ut aliquip ex ea commodo consequat.
>
> It is OK for the function documentation to start with a 2-space
> indentation, and none after that?
One of several possible thoughts on this:
I would hope that doc systems handle the availability of multi-string
doc, since it's permitted in the language.
(defun foo (x)
"abc" ; doc
"def" ; doc
(foo) ; body
"xyz" ; body
(bar) ; body
"baz" ; body
)
I like to think the way these would be joined in doc is
with an intervening newline, since that supports the obvious use
and the visual effect. I doubt many people want to or do use
(defun foo (x)
"this" " " "is" " " "a" " " "comment"
(foo))
- - - -
This happens not to be the solution I use, nor that I prefer.
But I think it should be an option, and it's rarely mentioned in
discussions like this, so I'm posting it to see what other say
about the notion.
On Jul 9, 8:33 am, Kent M Pitman <······@nhplace.com> wrote:
> Tamas Papp <······@gmail.com> writes:
> > I wonder what is the "proper" way to handle indentations and
> > linebreaks in documentation strings. If I just keep typing and press
> > C-Q, SLIME will indent it like this:
>
> > (defun foo (x)
> > "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
> > do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
> > enim ad minim veniam, quis nostrud exercitation ullamco laboris
> > nisi ut aliquip ex ea commodo consequat."
> > (1+ x))
>
> > Then (describe 'foo) gives:
>
> > Function documentation:
> > Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
> > do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
> > enim ad minim veniam, quis nostrud exercitation ullamco laboris
> > nisi ut aliquip ex ea commodo consequat.
>
> > It is OK for the function documentation to start with a 2-space
> > indentation, and none after that?
>
> One of several possible thoughts on this:
>
> I would hope that doc systems handle the availability of multi-string
> doc, since it's permitted in the language.
Having had various issues with implementations behaving differently
depending on the order of decl* and documentation, e.g., recognizing a
declaration in
(defun foo (x) "Doc string" (declare ...) ...)
but not in
(defun foo (x) (declare ...) "Doc string" ...)
(where the bodies /do/ contain forms), I had to read up on the syntax
specifications in the spec (the hyperspec, anyways). For defun, I see
(http://www.lispworks.com/documentation/HyperSpec/Body/m_defun.htm)
defun function-name lambda-list [[declaration* | documentation]] form*
and that
Arguments and Values:
declaration---a declare expression; not evaluated.
documentation---a string; not evaluated.
So I can understand multiple declarations, and even multiple
declarations with a single doc-string placed somewhere in between, but
I'm not clear how multiple strings can be used as documentation in
defun. Is there a cleanup issue that dealt with this, or am I
misreading
(x [[A | B* | C]] y)
means that at most one A, any number of B's, and at most one C can
occur in any order.
which appears at http://www.lispworks.com/documentation/HyperSpec/Body/01_daba.htm
Thanks!
>
> (defun foo (x)
> "abc" ; doc
> "def" ; doc
> (foo) ; body
> "xyz" ; body
> (bar) ; body
> "baz" ; body
> )
>
> I like to think the way these would be joined in doc is
> with an intervening newline, since that supports the obvious use
> and the visual effect. I doubt many people want to or do use
>
> (defun foo (x)
> "this" " " "is" " " "a" " " "comment"
> (foo))
>
> - - - -
>
> This happens not to be the solution I use, nor that I prefer.
> But I think it should be an option, and it's rarely mentioned in
> discussions like this, so I'm posting it to see what other say
> about the notion.
From: Kent M Pitman
Subject: Re: indenting the documentation string
Date:
Message-ID: <ubqel87gl.fsf@nhplace.com>
Joshua Taylor <···········@gmail.com> writes:
> Having had various issues with implementations behaving differently
> depending on the order of decl* and documentation, e.g., recognizing a
> declaration in
>
> (defun foo (x) "Doc string" (declare ...) ...)
>
> but not in
>
> (defun foo (x) (declare ...) "Doc string" ...)
>
> (where the bodies /do/ contain forms), I had to read up on the syntax
> specifications in the spec (the hyperspec, anyways).
Yeah, I think both of those should be accepted, but I'm not surprised
there have been bugs.
> For defun, I see
> (http://www.lispworks.com/documentation/HyperSpec/Body/m_defun.htm)
>
> defun function-name lambda-list [[declaration* | documentation]] form*
>
> and that
>
> Arguments and Values:
> declaration---a declare expression; not evaluated.
> documentation---a string; not evaluated.
>
> So I can understand multiple declarations, and even multiple
> declarations with a single doc-string placed somewhere in between, but
> I'm not clear how multiple strings can be used as documentation in
> defun.
Memory error on my part. Sorry for getting your hopes up. I always
wanted that to work, and I guess I didn't get it nudged into the
language.
> Is there a cleanup issue that dealt with this, or am I
> misreading
>
> (x [[A | B* | C]] y)
>
> means that at most one A, any number of B's, and at most one C can
> occur in any order.
>
> which appears at
> http://www.lispworks.com/documentation/HyperSpec/Body/01_daba.htm
>
> Thanks!
As far as I know, you're reading correctly. It's me that's wrong. Oh well.
On Jul 9, 7:48 pm, Kent M Pitman <······@nhplace.com> wrote:
> Joshua Taylor <···········@gmail.com> writes:
> > Having had various issues with implementations behaving differently
> > depending on the order of decl* and documentation, e.g., recognizing a
> > declaration in
>
> > (defun foo (x) "Doc string" (declare ...) ...)
>
> > but not in
>
> > (defun foo (x) (declare ...) "Doc string" ...)
>
> > (where the bodies /do/ contain forms), I had to read up on the syntax
> > specifications in the spec (the hyperspec, anyways).
>
> Yeah, I think both of those should be accepted, but I'm not surprised
> there have been bugs.
>
> > For defun, I see
> > (http://www.lispworks.com/documentation/HyperSpec/Body/m_defun.htm)
>
> > defun function-name lambda-list [[declaration* | documentation]] form*
>
> > and that
>
> > Arguments and Values:
> > declaration---a declare expression; not evaluated.
> > documentation---a string; not evaluated.
>
> > So I can understand multiple declarations, and even multiple
> > declarations with a single doc-string placed somewhere in between, but
> > I'm not clear how multiple strings can be used as documentation in
> > defun.
>
> Memory error on my part. Sorry for getting your hopes up. I always
> wanted that to work, and I guess I didn't get it nudged into the
> language.
>
> > Is there a cleanup issue that dealt with this, or am I
> > misreading
>
> > (x [[A | B* | C]] y)
>
> > means that at most one A, any number of B's, and at most one C can
> > occur in any order.
>
> > which appears at
> >http://www.lispworks.com/documentation/HyperSpec/Body/01_daba.htm
>
> > Thanks!
>
> As far as I know, you're reading correctly. It's me that's wrong. Oh well.
That's a shame; I was hoping I'd be demonstrated wrong. Being able to
mix declarations and doc strings (that would be concatenated together)
could have been very nice, if used judiciously, perhaps in a literate
programming style, and maybe some documentation generation tools.
(defun foo (bar baz)
"Foo the bar with the baz where "
(declare ...) "- list is a list of quux and"
(declare ...) "- bar and baz are ..."
....)
or something.
From: Don Geddis
Subject: Re: indenting the documentation string
Date:
Message-ID: <87bqeljtez.fsf@geddis.org>
Tamas Papp <······@gmail.com> wrote on Mon, 09 Jul 2007:
> (defun foo (x)
> "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
> do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
> enim ad minim veniam, quis nostrud exercitation ullamco laboris
> nisi ut aliquip ex ea commodo consequat."
> (1+ x))
>
> Then (describe 'foo) gives:
> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
> do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
> enim ad minim veniam, quis nostrud exercitation ullamco laboris
> nisi ut aliquip ex ea commodo consequat.
This is kind of an implementation error, isn't it? There are zero spaces in
front of any of the lines in the doc string. There's an odd coincidence that
the first line of the doc string is indented a couple of characters in the
definition, and also in the DESCRIBE output. But that's just a coincidence.
The implementation is _adding_ a couple of spaces when it prints out the
DESCRIBE documentation string. Surely, if it wants to do that, it should
also add spaces on subsequent lines. Or not add spaces to any of the lines.
Probably the implementation is just being lazy and doing something like
(format t "Doc string:~% ~A~%" doc-string)
But that has nothing to do with how emacs indents the string, nor with how
some other implementation might display it.
The last thing I'd do is alter the contents of your documentation string in
order to match the accidental debugging output of the implementation.
-- Don
_______________________________________________________________________________
Don Geddis http://don.geddis.org/ ···@geddis.org
Solution to two of the world's problems: Feed the homeless to the hungry.
Don Geddis <···@geddis.org> writes:
> Tamas Papp <······@gmail.com> wrote on Mon, 09 Jul 2007:
>> (defun foo (x)
>> "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
>> do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
>> enim ad minim veniam, quis nostrud exercitation ullamco laboris
>> nisi ut aliquip ex ea commodo consequat."
>> (1+ x))
>>
>> Then (describe 'foo) gives:
>> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
>> do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
>> enim ad minim veniam, quis nostrud exercitation ullamco laboris
>> nisi ut aliquip ex ea commodo consequat.
>
> This is kind of an implementation error, isn't it?
Not really. The output of DESCRIBE is implementation specific.
On the other hand (DOCUMENTATION 'FOO 'FUNCTION) should return either
NIL or the docstring as is.
Then you can write your own function MY-DESCRIBE that will be able to
format the docstring as you want. For example, engraving it into
marble sheets.
--
__Pascal Bourguignon__ http://www.informatimago.com/
NOTE: The most fundamental particles in this product are held
together by a "gluing" force about which little is currently known
and whose adhesive power can therefore not be permanently
guaranteed.