What goes into a documentation string?
Louis Glassy
go into a documentation string? For a small program I am working
on, I'm just describing in rough terms what the function does,
e.g.
(defun convert-text-to-bignum (line-of-text)
"(convert-text-to-bignum TEXT-STRING) - convert TEXT-STRING
into a bignum, with the digits of the bignum being just
the concatenated values of the decimal digits in the character
codes of the characters in TEXT-STRING"
(reduce #'decimal-shift-left-3-add
(mapcar #'char-code (coerce line-of-text 'list))))
or
(defun extract-right-fragment (bignum)
"(extract-right-fragment NUMBER) - extract the rightmost
three digits of NUMBER, return as an integer"
(mod bignum 1000))
If you are browsing through someone else's code, what do you
like to see in documentation strings?
Thanks in advance,
-lou
Marco Antoniotti
Louis Glassy <gla...@caesar.cs.montana.edu> writes:
There is a consensus as far as as Emacs Lisp is concerned. I use that
style for CL as well.
Your examples would read as
(defun convert-text-to-bignum (text-string)
"Convert TEXT-STRING into a bignum.
The digits of the bignum being just the concatenated values of the
decimal digits in the character codes of the characters in TEXT-STRING."
(reduce #'decimal-shift-left-3-add
(mapcar #'char-code (coerce line-of-text 'list))))
(defun extract-right-fragment (bignum)
"Extracts the rightmost three digits of BIGNUM, return as an integer."
(mod bignum 1000))
As you can see the first *line* describes what the things is or does,
the remaining lines (if necessary) go into details.
A full stop always ends the doc string.
This format is a requirement in Emacs/Elisp. Packages have been
refused entrance in the 'lisp' directory because of this.
When ILISP 5.9 will be out, you can try to diff it with 5.8 and see
what I have been doing all this time :)
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
Barry Margolin
Marco Antoniotti <mar...@copernico.parades.rm.cnr.it> wrote:
>This format is a requirement in Emacs/Elisp. Packages have been
>refused entrance in the 'lisp' directory because of this.
This is because Emacs has routines that depend on the first line being a
useful summary. In particular, apropos displays just the first line, so it
can be confusing if it's incomplete or ends in a sentence fragment.
--
Barry Margolin, bar...@bbnplanet.com
GTE Internetworking, Powered by BBN, Burlington, MA
*** DON'T SEND TECHNICAL QUESTIONS DIRECTLY TO ME, post them to newsgroups.
Please DON'T copy followups to me -- I'll assume it wasn't posted to the group.
Kent M Pitman
> Is there a consensus among Lisp programmers about what should
> go into a documentation string?
I almost never use them unless I have an application-specific automatic
documentation generation need. At that point, I use whatever my program
expects. As a rule, I consider it stylistically a modularity violation
to ask for documentation of someone else's doc string and expect to use
it for anything other than to dump it raw to the console as
archaeology-style debugging clues. It perhaps shouldn't have gone this
way, but years of divergent experience make little else feasible.
The same is true of various other unconstrained strings like
that returned by (lisp-implementation-version), which is not adequately
constrained to use in a format string other than
"(lisp-implementation-version) returned this: ~S"
The only strings that I still hold any hope of having constraint, really,
are error message strings, because the standard goes on a limb in describing
their linguistic shape as a hint, and check-type arguments, which I seriously
wish I could talk Harlequin (and others) into not doing, as they do in
LWW 4.1:
(let ((x 13)) (check-type x (integer 1 12) "a month number"))
Error: The value 13 of X is not of type "a month number"
and instead doing:
(let ((x 13)) (check-type x (integer 1 12) "a month number"))
Error: The value 13 of X is not a month number.
as the Lisp Machine does. That is, they should, IMO, use:
"The value ~S of ~S is not ~A."
instead of
"The value ~S of ~S is not of type ~S."
Yes, this requires some heuristic assembly when no user-supplied doc
string is given. And yes, I've bug reported this. Long ago when I was
an employee, and I think recently again as a customer, though I might
be wrong on that. Drives me seriously nuts. The language is intended to
look nice to users, and the present behavior goes out of its way not to.
Back to doc strings, though, whiel the details of what I put in doc
strings varies, the classical problem of doc strings is less of an issue
in modern systems. Specifically, I think the reason doc strings never
took off was the problem of:
(defun foo1 (x)
"Do I do
this?")
vs
(defun foo2 (x)
"Do I do
this?")
I had proposed early on that multiple doc strings should be appended with
a newline between so that
(defun foo3 (x)
"Do I do"
"this?")
would mean a two-line string with a flush left margin. The failure to
solve this problem made most output of doc strings look goofy and that
is why I think they got little play. Some people took advantage of it
to have the FOO1 case print continuation lines indented and they liked
it but most people just hated it all around. Now with HTML and autofill
of text, one can just slap this stuff into an HTML file and both solve
this problem as well as other formatting problems, and I often now
put HTML in my doc strings on the few occasions I use them at all.
Vassil Nikolov
[...]
> the problem of:
>
> (defun foo1 (x)
> "Do I do
> this?")
I can live with a top-level DEFUN like
(defun foo (x)
"A documentation
string"
...)
but FLET etc. doc-strings which tend to start way to the right really
put me off.
> vs
>
> (defun foo2 (x)
> "Do I do
> this?")
>
> I had proposed early on that multiple doc strings should be appended with
> a newline between so that
>
> (defun foo3 (x)
> "Do I do"
> "this?")
>
> would mean a two-line string with a flush left margin.
Or perhaps some analogue to FORMAT's ``~<newline>''?
> The failure to
> solve this problem made most output of doc strings look goofy and that
> is why I think they got little play. Some people took advantage of it
> to have the FOO1 case print continuation lines indented and they liked
Isn't it FOO2?
> it but most people just hated it all around. Now with HTML and autofill
> of text, one can just slap this stuff into an HTML file and both solve
> this problem as well as other formatting problems, and I often now
> put HTML in my doc strings on the few occasions I use them at all.
Another thing about doc-strings which it would be nice to have
standardised (though it is of low priority) is to guarantee that there
is no need to put arglist information in them (which could be provided
automatically by the implementation).
Vassil Nikolov
Permanent forwarding e-mail: vnik...@poboxes.com
For more: http://www.poboxes.com/vnikolov
Abaci lignei --- programmatici ferrei.
Sent via Deja.com http://www.deja.com/
Share what you know. Learn what you don't.
Tom Breton
> Back to doc strings, though, whiel the details of what I put in doc
> strings varies, the classical problem of doc strings is less of an issue
> in modern systems. Specifically, I think the reason doc strings never
> took off was the problem of:
>
> (defun foo1 (x)
> "Do I do
> this?")
>
> vs
>
> (defun foo2 (x)
> "Do I do
> this?")
>
> I had proposed early on that multiple doc strings should be appended with
> a newline between so that
>
> (defun foo3 (x)
> "Do I do"
> "this?")
> would mean a two-line string with a flush left margin.
This has its advantages, but requires some weirdness if you want to
return a constant string.
(defun foo3 (x)
"Demonstrate weirdness."
"I'd like to return this string, but nooooooo....."
nil
"So I'll hack around it by including a gratuitous nil.")
I won't talk you about what winnowed comments could do for
documentation, 'cuz I know that idea bothers you.
> The failure to
> solve this problem made most output of doc strings look goofy and that
> is why I think they got little play.
Possibly.
--
Tom Breton, http://world.std.com/~tob
Ugh-free Spelling (no "gh") http://world.std.com/~tob/ugh-free.html
Kent M Pitman
> > I had proposed early on that multiple doc strings should be appended with
> > a newline between so that
> >
> > (defun foo3 (x)
> > "Do I do"
> > "this?")
>
> > would mean a two-line string with a flush left margin.
>
> This has its advantages, but requires some weirdness if you want to
> return a constant string.
This problem is no different without my proposal.
(defun foo ()
"I wonder if this is a doc string.")
Paolo Amoroso
wrote:
> Is there a consensus among Lisp programmers about what should
> go into a documentation string? For a small program I am working
I profit by the occasion to ask a related question. According to the Emacs
Lisp convention, the verb in the first sentence of the documentation
string, as well as in the rest of the first paragraph, should be phrased as
an infinitive with "to" omitted (e.g. "Return the cons of A and B" in
preference to "Returns the cons of A and B"). Subsequent paragraphs should
have proper subjects.
I have seen Common Lisp code that both follows the Emacs Lisp convention
(e.g. "Return" in the example above) and doesn't follow it (e.g.
"Returns"). Is there a "preferred" or "most popular" convention for Common
Lisp? I haven't enough experience to answer this question.
From my limited knowledge of English, it seems that both ways are
acceptable in the proper "frame of reference". The Emacs Lisp one reminds
me of the notes on theatrical plots (e.g. the imperative "Enter Polonius"),
while the other convention is consistent with the ordinary use of English
(e.g. "Enters Polonius"--or better(?) "Polonius enters"--with the third
person).
> (defun convert-text-to-bignum (line-of-text)
> "(convert-text-to-bignum TEXT-STRING) - convert TEXT-STRING
[...]
> (defun extract-right-fragment (bignum)
> "(extract-right-fragment NUMBER) - extract the rightmost
Isn't it redundant to repeat the function name?
> If you are browsing through someone else's code, what do you
> like to see in documentation strings?
Well, I'd like to see a documentation string in the first place :)
Paolo
--
Paolo Amoroso <amo...@mclink.it>
Otto-Ville Ronkainen
>I profit by the occasion to ask a related question. According to the Emacs
>Lisp convention, the verb in the first sentence of the documentation
>string, as well as in the rest of the first paragraph, should be phrased as
>an infinitive with "to" omitted (e.g. "Return the cons of A and B" in
>preference to "Returns the cons of A and B"). Subsequent paragraphs should
>have proper subjects.
Um, I've always parsed those as imperatives (which go nicely with
function names usually containing a finite verb of that mode).
Kent M Pitman
> In article <37b32d1...@news.mclink.it> amo...@mclink.it
> (Paolo Amoroso) writes:
>
> > the verb ... should be phrased as an infinitive with "to" omitted
> > Subsequent paragraphs should have proper subjects.
>
> Um, I've always parsed those as imperatives (which go nicely with
> function names usually containing a finite verb of that mode).
And so you should. ;-)
I personally don't like documentation that is super-imperative like
some others seem to like. I've had to move more toward it over time,
in spite of how rude it appears to me, because I've seen various people
interpret "You really, really should do x" as formally equivalent to
"You don't have to do x" because (they claim) if it isn't a "shall",
it's not required, and if it's not required, it's optional, and there's
really not any more to it than that. Personally, I think this is
nutty. To me, if someone says "You should do x" and provides you with
no alternative behavior, it may be that you're not required but on
the other hand you'd better not expect much of any predictable
behavior if you do other than x. The difference between "You're not
required but the behavior may be unpredictable if you don't" and
"You are required becuase the behavior may be unpredictable if you don't"
is extremely subtle, to the point of being lost on me.
I noticed in prep for the ISO ISLISP spec that many Europeans, and
particularly the Germans, were really worried every time I'd even say
"something will happen" and wanted me to rewrite this as
"something shall happen" as if somehow this made it stronger.
This week in German class we were looking at the German word "will"
and I found myself wondering if this was just a false cognate for them;
in my dialect of English, "will" is either imperative or unconditionally
predictive, which amounts to the same in computerspeak. I know in some
English dialects there is a subtle difference, but it's lost on me.
There's some joke in which a drowning man is left to die because he says
either
"everyone, i will drown and no one shall save me"
or
"everyone, i shall drown and no one will save me"
i think it's the former, but i have to say that neither of these sounds
any different to my ear. in my dialect, "will" is interchangable
with "shall" and the only difference is that "shall" has the property
of sounding more erudite/snobby.
it's complicated when we share a common language that varies in sense and
meaning this way.
Paolo Amoroso
wrote:
> Louis Glassy <gla...@caesar.cs.montana.edu> writes:
>
> > Is there a consensus among Lisp programmers about what should
> > go into a documentation string?
>
> I almost never use them unless I have an application-specific automatic
> documentation generation need. At that point, I use whatever my program
How do you document your code? With comments? With separate documents? Or
maybe you write the code so that it is as self documenting as possible?
Michael Schuerig
> I noticed in prep for the ISO ISLISP spec that many Europeans, and
> particularly the Germans, were really worried every time I'd even say
> "something will happen" and wanted me to rewrite this as
> "something shall happen" as if somehow this made it stronger.
> This week in German class we were looking at the German word "will"
> and I found myself wondering if this was just a false cognate for them;
> in my dialect of English, "will" is either imperative or unconditionally
> predictive, which amounts to the same in computerspeak.
Indeed, the likely reason is that to the german folks "something will
happen" has a ring of "someone wants something to happen". Well, someone
may want it, but it might not happen nevertheless. For my ears -- I am
german -- the english "will" is strongly connected to the german
"wollen" ("to want", 1P: "ich will"). Also, if something *shall*
("soll"/"ought to") happen, this implies accordance with a higher,
law-like order or authority.
I find the "shall"/"sollen" rather annoying. It's second only to "etwas
hat zu passieren"/"something has to happen", a phrase that's much worse
in german than it is in english. I feel more comfortable knowing that
something *will* happen, given that its preconditions are satisfied.
Michael
--
Michael Schuerig
mailto:schu...@acm.org
http://www.schuerig.de/michael/
Vassil Nikolov
[...]
[on `shall' vs. `should' etc.]
Is there anything wrong with `must'? I.e. if I used `must' and never
`shall,' would that sound too imperative as well?
Kent M Pitman
> Kent M Pitman wrote: [1999-08-13 17:46 +0000]
>
> [...]
> [on `shall' vs. `should' etc.]
>
> Is there anything wrong with `must'? I.e. if I used `must' and never
> `shall,' would that sound too imperative as well?
I think the problem with "must" is that it requires an explicit or implicit
description of someone who takes on the obligation. The distinction that
many documents seem to use is approximately that "must" is an obligation
on the programmer and "shall" is an obligation on the system.
"The value must be an integer."
"If the value is not an integer, an error shall be signalled."
I personally hate the "shall" here since it implies there is an
element of force, and to me the sense of it (German intuitions
notwithstanding; this is not a conjugation of "wollen" taken out of
context, this is an English word with English meaning) is that "shall"
is weaker, not stronger, than "will". Because--to me, anyway--"shall"
implies force, but the need for force in the first place implies the
possibility of a failure of the force to suffice, which implies the
possibility that the imperative will not be satisfied if the system
becomes (pardon the pun here, but this *is* the right English word here)
"willful". By contrast, in my dialect of English, "will" implies a
mere statement of unconditional future truth [as if an unmovable destiny
given by a fortune teller] and is therefore not subject to escape.
Back to your question, though, to use only "must" (or only "shall"/"will",
for that matter) would leave some situations clear and others not.
The problem case is the multie-dimensional table of responsibility
that marks the difference between what CHECK-TYPE checks for and what
ASSERT checks for [if you ignore the issue of type specifiers, which also
differs between these but is not relevant to this choice of analogy]. To
be clear, if I said:
"The argument x must be an integer."
there would be no amibguity because programmers pass arguments, and
pragmatically the responsibility is clearly on the programmer. Likewise,
if you say
"The result of + must be a number."
there is again no ambiguity. Those are the two CHECK-TYPE-like
cases. But if you say something where two are different, as in:
"The result must be compatible with the input."
then you have the ASSERT-like case where you have two inputs either of which
might be wrong and the word "must" doesn't suffice. If you reframe this
in terms of responsibility of either the programmer or the system, you get a
better result. The split use of "shall" (to refer to the system) and
"must" (to refer to programmer) would be one way to do that. That's not to
say that the English word "must" implies this, but only to say that the
choice of two words rather than a single word can create a convention in
which the implication exists.
Of course, extra words can also help. But people hate it when specs get
wordy--that's one thing I definitely know. So there are no perfect
solutions.
Lieven Marchand
> I personally hate the "shall" here since it implies there is an
> element of force, and to me the sense of it (German intuitions
> notwithstanding; this is not a conjugation of "wollen" taken out of
> context, this is an English word with English meaning) is that "shall"
> is weaker, not stronger, than "will". Because--to me, anyway--"shall"
> implies force, but the need for force in the first place implies the
> possibility of a failure of the force to suffice, which implies the
> possibility that the imperative will not be satisfied if the system
> becomes (pardon the pun here, but this *is* the right English word here)
> "willful". By contrast, in my dialect of English, "will" implies a
> mere statement of unconditional future truth [as if an unmovable destiny
> given by a fortune teller] and is therefore not subject to escape.
As a foreign speaker of English, I allways had the impression the
whole "shall/will/must" mess was standardese. ANSI CL doesn't seem to
do it, but ISO C and other ANSI/ISO standards, IEEE standards and
OpenGroup standards define their use of these words in very fine
detail.
--
Lieven Marchand <m...@bewoner.dma.be>
If there are aliens, they play Go. -- Lasker
Rob Warnock
| I noticed in prep for the ISO ISLISP spec that many Europeans, and
| particularly the Germans, were really worried every time I'd even say
| "something will happen" and wanted me to rewrite this as
| "something shall happen" as if somehow this made it stronger.
| This week in German class we were looking at the German word "will"
| and I found myself wondering if this was just a false cognate for them;
| in my dialect of English, "will" is either imperative or unconditionally
| English dialects there is a subtle difference, but it's lost on me.
If I'm recalling correctly (and I'm not at all sure it's 100% correct),
what I was taught in high school English was that which of "shall/will"
meant indicative/imperative depended on the "person" of the sentence:
Indicative Imperative
Singular Plural Singular Plural
1st-person I shall... We will... I/we will... We shall...
2nd-person You will... You will... You shall... You shall...
3rd-person He/She shall... They will... He/She will... They shall...
Though clearly the subtleties of the 1st- & 3rd-person forms have been
generally lost in recent common usage....
-Rob
-----
Rob Warnock, 8L-855 rp...@sgi.com
Applied Networking http://reality.sgi.com/rpw3/
Silicon Graphics, Inc. Phone: 650-933-1673
1600 Amphitheatre Pkwy. FAX: 650-933-0511
Mountain View, CA 94043 PP-ASEL-IA
Vassil Nikolov
[about `shall' vs. `must']
Thank you for the further explanation.
I don't know if I will (shall? must? may?) ever master this,
but at least I am ever improving...
Vassil Nikolov
[...]
> As a foreign speaker of English, I allways had the impression the
> whole "shall/will/must" mess was standardese. ANSI CL doesn't seem to
> do it, but ISO C and other ANSI/ISO standards, IEEE standards and
> OpenGroup standards define their use of these words in very fine
> detail.
In my own experience, I learned about this `shall/must' vs. the others
stuff first in the context of requirements, which is perhaps some kind
of legalese (and is standardese not a subclass of legalese?), by being
told that if it doesn't say `shall' or `must' it might as well be omitted.
I don't know how reasonable the rules of the game are, but at least it
helps to know about them.
By the way, I try to speak and write British English (and not American
English, because Britain is nearer geographically if for not better
reason^1), but I suspect I am at most moderately successful in that;
but I believe I can safely claim I speak perfect Balkan English...
__________
^1 though this should require of myself to use EU English now...
(International Standard English, anyone?)
[Once I talked to an American about the English language and I said
that becoming the language of the world has the effect of everybody
speaking it in their own way and `spoiling' it; his response was, `Don't
worry, we'll fix it...']
Vassil Nikolov
[...]
> Indicative Imperative
> Singular Plural Singular Plural
> 1st-person I shall... We will... I/we will... We shall...
> 2nd-person You will... You will... You shall... You shall...
> 3rd-person He/She shall... They will... He/She will... They shall...
[...]
That's what my textbooks and dictionaries say, but as usual reality is
somewhat more complicated. (Sometimes I get the illusion that I
have mastered the `shall/will' distinction, then I realise I haven't
but I guess even native speakers aren't perfect.)
Rolf-Thomas Happe
> If I'm recalling correctly (and I'm not at all sure it's 100% correct),
> what I was taught in high school English was that which of "shall/will"
> meant indicative/imperative depended on the "person" of the sentence:
> Though clearly the subtleties of the 1st- & 3rd-person forms have been
> generally lost in recent common usage....
According to Style:_Towards_Clarity_and_Grace by Joseph M. Williams,
this is an artificial rule most speakers/writers don't comply with,
including writers who care for their language. (The book exposes
several such "rules" scholars once made up, and pop grammarians
still both preach and don't obey.)
BTW, Williams' book is the style guide Richard P. Gabriel
recommends in Patterns_of_Software.
rthappe
Kent M Pitman
> If I'm recalling correctly (and I'm not at all sure it's 100% correct),
> what I was taught in high school English was that which of "shall/will"
> meant indicative/imperative depended on the "person" of the sentence:
>
> Indicative Imperative
> Singular Plural Singular Plural
> 1st-person I shall... We will... I/we will... We shall...
> 2nd-person You will... You will... You shall... You shall...
> 3rd-person He/She shall... They will... He/She will... They shall...
>
> Though clearly the subtleties of the 1st- & 3rd-person forms have been
> generally lost in recent common usage....
Yes, this is what was taught to me in school, but no one I know speaks
like that. It's just one of those things where you nod politely at your
teacher and then go on doing what the language really does... Languages
evolve, and it's the job of grammar teachers to pretend that's not so.
William Deakin
> I don't know if I will (shall? must? may?) ever master this, but at
> least I am ever improving...
What about can, should, be required, obliged, allowed, ought, have to or
want to...?
:-) will
Marco Antoniotti
amo...@mclink.it (Paolo Amoroso) writes:
> On Thu, 12 Aug 1999 15:38:00 GMT, Kent M Pitman <pit...@world.std.com>
> wrote:
>
> > Louis Glassy <gla...@caesar.cs.montana.edu> writes:
> >
> > > Is there a consensus among Lisp programmers about what should
> > > go into a documentation string?
> >
> > I almost never use them unless I have an application-specific automatic
> > documentation generation need. At that point, I use whatever my program
>
> How do you document your code? With comments? With separate documents? Or
> maybe you write the code so that it is as self documenting as possible?
By definition, code is self-documenting. :)
Daniel Barlow
> either
> "everyone, i will drown and no one shall save me"
> or
> "everyone, i shall drown and no one will save me"
Strunk and White, The Elements of Style (3rd ed, 1979) says:
A swimmer in distress cries, ``I shall drown; no one will save me!''
A suicide puts it the other way: ``I will drown; no one shall save
me!'' In relaxed speech, however, the words /shall/ and /will/ are
seldom used precisely; our ear guides us or fails to guide us, as
the case may be, and we are quite likely to drown when we want to
survive and survive when we want to drown.
Still, "shall" sounds affected to me, so I use "will" in all
circumstances. I guess I'm not wavering but drowning.
-dan, not drawning but waving