Is DOCUMENTATION passe?
Peter Seibel
2.30, and SBCL 0.7.8) there are no DOCUMENTATION strings available for
the small sample of functions in the COMMON-LISP package. (SBCL had
them.) Is that because nobody finds DOCUMENTATION that useful? Or
because people are expected to know what the functions defined in
COMMON-LISP are for? Or am I just missing something about how to
configure/install those implementations so as to have the
documentation strings available.
What about packages other than COMMON-LISP? Do folks expect libraries
to come with documentation strings so they can get at documentation
via the DOCUMENTATION function. Or does everybody just use some form
of HTML documentation these days?
-Peter
--
Peter Seibel pe...@javamonkey.com
Lisp is the red pill. -- John Fraser, comp.lang.lisp
Kenny Tilton
Peter Seibel wrote:
> I've just noticed that in two out of three CL's tested (ACL 6.2, CLISP
> 2.30, and SBCL 0.7.8) there are no DOCUMENTATION strings available for
> the small sample of functions in the COMMON-LISP package. (SBCL had
> them.) Is that because nobody finds DOCUMENTATION that useful? Or
> because people are expected to know what the functions defined in
> COMMON-LISP are for? Or am I just missing something about how to
> configure/install those implementations so as to have the
> documentation strings available.
I do get the function signature as soon as I finish typing the fn name,
and usually that is my only question (ie, yes, after a while one knows
what the CL functions do). If I need more, I use ACL where F1 takes me
to the glorious HyperSpec.
>
> What about packages other than COMMON-LISP? Do folks expect libraries
> to come with documentation strings so they can get at documentation
> via the DOCUMENTATION function. Or does everybody just use some form
> of HTML documentation these days?
This only came up with ACL add-on's such as their GUI or sockets. There
I have deeper questions a doc string would not be able to help with.
That said, I am starting to use doc strings in the RoboCup client I am
developing for folks to use at ILC 2003. I figure, hell, if I am going
to toss in a comment, I may as well make it a doc string for whatever
small extra benefit comes of it being accessible that way.
--
kenny tilton
clinisys, inc
http://www.tilton-technology.com/
---------------------------------------------------------------
"Career highlights? I had two. I got an intentional walk from
Sandy Koufax and I got out of a rundown against the Mets."
-- Bob Uecker
Peter Seibel
> I do get the function signature as soon as I finish typing the fn
> name, and usually that is my only question
Speaking of which, does anyone know how to get ELI to do this--I
recently switched from ILISP to ELI and that's the one thing I
miss--having the signature pop up in my mini-buffer as soon as I type
a name.
Kent M Pitman
> I've just noticed that in two out of three CL's tested (ACL 6.2, CLISP
> 2.30, and SBCL 0.7.8) there are no DOCUMENTATION strings available for
> the small sample of functions in the COMMON-LISP package. (SBCL had
> them.) Is that because nobody finds DOCUMENTATION that useful? Or
> because people are expected to know what the functions defined in
> COMMON-LISP are for? Or am I just missing something about how to
> configure/install those implementations so as to have the
> documentation strings available.
It's an environment issue. Implementations were never intended to be
required to have these. Some have auxiliary documentation of other kinds.
Also, it implies various things about memory management that are disagreed
upon by implementors. Each implementor is expected to know its user
community. It's just that some people use functional doc strings and
DOCUMENTATION allows you access when they do. No implementation was ever
expected to be required to do this for system functions. Some do. But
a lot, too, this might be about "user functions only" in some
implementations. So there are really two orthogonal bits:
- does the implementation even record doc strings (this is
optional in and of itself)
- does the implementation have doc strings for CL functions
> What about packages other than COMMON-LISP? Do folks expect libraries
> to come with documentation strings so they can get at documentation
> via the DOCUMENTATION function.
It's DEFINITELY not required. If they expect this, they are wrong.
It was never required, therefore "passe" is the wrong word.
It was something some implementations did and people wanted an accessor
just in case they were using such an implementation. It's up to vendors
as a "quality of implementation" issue to know whether their user group
needs this in order to be happy and/or whether this is appropriate to
their implementation's "style".
> Or does everybody just use some form of HTML documentation these days?
Asking about "everybody" is and always has been completely the wrong
question. Implementations were never expected to agree on this nor any
of the environment-related functions (for "environment" here, I mean
"programming support substrate" not the things you get in an &environment
argument :)...
Daniel Barlow
> I've just noticed that in two out of three CL's tested (ACL 6.2, CLISP
> 2.30, and SBCL 0.7.8) there are no DOCUMENTATION strings available for
> the small sample of functions in the COMMON-LISP package. (SBCL had
Most of the documentation in SBCL was inherited from CMUCL; I don't
_think_ we have a clear policy for docstrings in new functionality,
other than the general principle that it would be nice if you have
nothing better to do.
Note that recompiling SBCL without the :sb-doc feature will in
principle cause it to remove most (should be all) of the documentation
strings.
> What about packages other than COMMON-LISP? Do folks expect libraries
> to come with documentation strings so they can get at documentation
> via the DOCUMENTATION function. Or does everybody just use some form
> of HTML documentation these days?
My personal opinions (not speaking as an SBCL implementor)
* I like having documentation for SEARCH, because I can never
rememember the argument order, and the arglist (STRING1 STRING2)
is no help either. Usually for symbols in CL, though, either the
arglist is sufficient or I go direct to CLHS
* I find that writing documentation for a function is a pretty good
mental exercise to determine whether the function makes sense in the
first place: if I can't succintly describe what it does, I probably
don't know, and I should rearrange matters (by splitting/combining
functions or some other refactoring) so that I do.
-dan
--
http://www.cliki.net/ - Link farm for free CL-on-Unix resources
pat...@nordebo.com
> I've just noticed that in two out of three CL's tested (ACL 6.2, CLISP
> 2.30, and SBCL 0.7.8) there are no DOCUMENTATION strings available for
> the small sample of functions in the COMMON-LISP package. (SBCL had
> them.) Is that because nobody finds DOCUMENTATION that useful?
Well, I find them useful, though for the CL functions I usually look
in the Hyperspec instead, because I have sufficiently good Hyperspec
integration, and, as you observe, some implementations don't come with
docstrings anyway.
> What about packages other than COMMON-LISP? Do folks expect libraries
> to come with documentation strings so they can get at documentation
> via the DOCUMENTATION function. Or does everybody just use some form
> of HTML documentation these days?
I can't say I expect it, but I do find it very useful. Being able to
get at the function documentation easily from within Emacs makes me
feel all warm and fuzzy.
Thomas F. Burdick
> I've just noticed that in two out of three CL's tested (ACL 6.2, CLISP
> 2.30, and SBCL 0.7.8) there are no DOCUMENTATION strings available for
> the small sample of functions in the COMMON-LISP package. (SBCL had
> them.) Is that because nobody finds DOCUMENTATION that useful? Or
> because people are expected to know what the functions defined in
> COMMON-LISP are for? Or am I just missing something about how to
> configure/install those implementations so as to have the
> documentation strings available.
>
> What about packages other than COMMON-LISP? Do folks expect libraries
> to come with documentation strings so they can get at documentation
> via the DOCUMENTATION function. Or does everybody just use some form
> of HTML documentation these days?
I write docstrings for everything that's not painfully obvious. It's
really nice when you come across an old module and you don't quite
remember how it works. (frob-foo<SPACE> ... okay, there's the
argument signature, (FOO), that doesn't help -- let's check the
docstring.
As for others' libraries, I kind of view docstrings as one measure of
their quality/maturity. So, I don't necessarily expect them, but I do
hope for them, and libraries lacking them make me a little wary.
--
/|_ .-----------------------.
,' .\ / | No to Imperialist war |
,--' _,' | Wage class war! |
/ / `-----------------------'
( -. |
| ) |
(`-. '--.)
`. )----'
Marco Antoniotti
USER-MANUAL munged files and doc strings to produce pretty good
documentation.
Cheers
Marco
james anderson
as far back as i can remember, mcl's editor has defined c-x c-d to pop up a
window which, in the case of common-lisp definitions, had pretty much the same
description as cltl. i'm not sure if it was always the case, but it's in the
documentation for 2.0, which means ca. 1987. if i recall correctly, this
feature was not as much a matter of course as one might expect: they also did
a cltl permuted index, which did not stay in print very long.
Peter Seibel wrote:
> ...
>
> What about packages other than COMMON-LISP? Do folks expect libraries
> to come with documentation strings so they can get at documentation
> via the DOCUMENTATION function. Or does everybody just use some form
> of HTML documentation these days?
i tend to generate html documentation from the documentation strings, method
signatures, etc, which means the strings are there.
...
Bill Clementson
> recently switched from ILISP to ELI and that's the one thing I
> miss--having the signature pop up in my mini-buffer as soon as I type
> a name.
The following is an adaptation of the code from ILISP - it's not
rigorous, but it seems to do the job:
(defun eli-arglist-lisp-space ()
"Displays the value of the argument list of a symbol followed by
#\\Space.
This function is intended to be bound to the #\\Space key so that,
after being enabled it will display the arglist or value of a specific
symbol after the symbol has been typed in followed by #\\Space."
(interactive)
(let* ((old-point (point))
(last-char (progn (ignore-errors (backward-char))
(unless (eql (point) old-point)
(buffer-substring-no-properties old-point (point)))))
(string
(buffer-substring-no-properties old-point
(progn
(goto-char old-point)
(ignore-errors (backward-sexp))
(point))))
(prefix-char
(let ((save (ignore-errors
(goto-char old-point)
(backward-sexp)
(backward-char)
(point))))
(when save
(buffer-substring-no-properties save (1+ save)))))
(double-quote-pos (and string (string-match "\"" string)))
(paren-pos (and string
(string-match "(" string)))
(symbol-with-package
(unless (eql paren-pos 0)
(if (and double-quote-pos (eql double-quote-pos 0)
string (ignore-errors (elt string 2)))
(substring string 1 -1)
string)))
(symbol symbol-with-package))
(flet ((no-arglist-output-p ()
(or (and last-char
(or ;; don't do silly things after comment character
(equal last-char ";")
;; do something only if directly after a sexp.
(equal last-char " ")))
;; could be something like #+foo, #-foo, or #:foo, any of
;; which is likely to lose.
(and string
(string-match "^#" string))
double-quote-pos ;; there is no output for strings only.
(not (and symbol (stringp symbol) (> (length symbol) 0)))
(string-match "^\. " symbol)
(string-match "^\\\\" symbol))))
(goto-char old-point)
(unless (no-arglist-output-p)
;; only output for functions within brackets; too much lisp-traffic!
(when (equal prefix-char "(")
(fi::make-request (lep::arglist-session :fspec string)
;; Normal continuation
(() (what arglist)
(fi:show-some-text nil "%s's arglist: %s" what arglist))
;; Error continuation
((string) (error)
(fi::show-error-text "")))))))
(self-insert-command (prefix-numeric-value current-prefix-arg)))
Put it in your .emacs file with the following hook to activate it:
(setq fi:lisp-mode-hook
(function
(lambda ()
(let ((map (current-local-map)))
(define-key map " " 'eli-arglist-lisp-space)))))
Hope that helps.
--
Bill Clementson
Peter Seibel
> Peter Seibel <pe...@javamonkey.com> wrote in message
> > Speaking of which, does anyone know how to get ELI to do this--I
> > recently switched from ILISP to ELI and that's the one thing I
> > miss--having the signature pop up in my mini-buffer as soon as I type
> > a name.
>
> The following is an adaptation of the code from ILISP - it's not
> rigorous, but it seems to do the job:
Awsome. Thanks.
Stig E. Sandų
>Let's also remember that way before Javadoc and Doxygen the good old
>USER-MANUAL munged files and doc strings to produce pretty good
>documentation.
One might, or might not, find Albert useful. It's a doc-generator
for Common Lisp, comparable to Javadoc and Doxygen. It reads an ASDF
system definition and generates Docbook documentation for the system.
It grovels on the source-files and does not LOAD the system.
<URL: http://albert.sourceforge.net/>
It's mostly developed on-demand, so the good way of getting feature
FOO included/working is to suggest it and/or contribute patches.
--
------------------------------------------------------------------
Stig Erik Sandoe st...@ii.uib.no http://www.ii.uib.no/~stig/
Peter Seibel
> On Fri, 08 Aug 2003 18:10:05 -0400, Marco Antoniotti <mar...@cs.nyu.edu> wrote:
>
> >Let's also remember that way before Javadoc and Doxygen the good old
> >USER-MANUAL munged files and doc strings to produce pretty good
> >documentation.
>
> One might, or might not, find Albert useful. It's a doc-generator
> for Common Lisp, comparable to Javadoc and Doxygen. It reads an ASDF
> system definition and generates Docbook documentation for the system.
> It grovels on the source-files and does not LOAD the system.
>
> <URL: http://albert.sourceforge.net/>
Cool. I'll take a look. Thanks.