Constructed docstrings for closures

Constructed docstrings for closures

[Stefan Monnier]

When converting backquoted lambdas to closures, I've often bumped into
the following problem:

   `(lambda (foo bar)
      ,(concat "Toto is very " blabla ".")
      (code using foo and bar (and ',blabla as well)))

So code-wise, this can be replaced by a closure just fine, but doc-wise
we don't have a way to construct a different docstring for
every closure.

I'd like to lift this restriction by offering a new feature that lets us
do something like:

   (lambda (foo bar)
     <something-magical-here>
     (code using foo and bar (and blabla as well)))

and get the closure we want with the docstring we want.

Does anyone have an idea of what the <something-magical-here>
could/should be?


        Stefan

Re: Constructed docstrings for closures

[David Kastrup]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> When converting backquoted lambdas to closures, I've often bumped into
> the following problem:
>
>    `(lambda (foo bar)
>       ,(concat "Toto is very " blabla ".")
>       (code using foo and bar (and ',blabla as well)))
>
> So code-wise, this can be replaced by a closure just fine, but doc-wise
> we don't have a way to construct a different docstring for
> every closure.
>
> I'd like to lift this restriction by offering a new feature that lets us
> do something like:
>
>    (lambda (foo bar)
>      <something-magical-here>
>      (code using foo and bar (and blabla as well)))
>
> and get the closure we want with the docstring we want.
>
> Does anyone have an idea of what the <something-magical-here>
> could/should be?

Doing it the other way round seems much cleaner:

(with-doc-string
  (concat "Toto is very " blabla ".")
  (lambda (foo bar)
    (code using foo and bar (and blabla as well))))


-- 
David Kastrup

Re: Constructed docstrings for closures

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> I'd like to lift this restriction by offering a new feature that lets us
> do something like:
>
>    (lambda (foo bar)
>      <something-magical-here>
>      (code using foo and bar (and blabla as well)))
>
> and get the closure we want with the docstring we want.
>
> Does anyone have an idea of what the <something-magical-here>
> could/should be?

  (declare (comment (format "This is a comment about %s" bla)))

would be a natural syntax, I think?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Constructed docstrings for closures

[Lars Magne Ingebrigtsen]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

>   (declare (comment (format "This is a comment about %s" bla)))
>
> would be a natural syntax, I think?

I mean `documentation'.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Constructed docstrings for closures

[Stefan Monnier]

Lars suggests:
> (declare (comment (format "This is a comment about %s" bla)))
> would be a natural syntax, I think?

David prefers:
> Doing it the other way round seems much cleaner:
> (with-doc-string
>   (concat "Toto is very " blabla ".")
>   (lambda (foo bar)
>     (code using foo and bar (and blabla as well))))

There are various issues around this:
1- the code that constructs the docstring should be visible to the compiler
   (so the compiler can tell it where to find the value of the lexically
   scoped `blabla' variable).
2- it shouldn't slow down normal evaluation
3- it should be implementable without too much effort.

From that point of view I guess David's approach is promising on
the first two points, but I'm not sure what the 3rd point would
look like.

Lars's suggestion seems problematic w.r.t point #2 since `lambda' would
now have to check for a `declare'.

I considered using a special property on the docstring as well, but
that's problematic w.r.t point #1.

So please keep sending ideas.


        Stefan

Re: Constructed docstrings for closures

[Artur Malabarba]

> Lars suggests:
> > (declare (comment (format "This is a comment about %s" bla)))
> > would be a natural syntax, I think?
I agree this would be the most natural, but if it does slow down
evaluation (which I think it would), then it isn't worth the cost.
OTOH, it might be interesting to apply this logic to `defun's, since
they already handle `declare' forms anyway.

> David prefers:
> > Doing it the other way round seems much cleaner:
> > (with-doc-string
> >   (concat "Toto is very " blabla ".")
> >   (lambda (foo bar)
> >     (code using foo and bar (and blabla as well))))

If this is chosen, I would find the following form more natural:

(lambda-with-doc-string (foo bar)
  ;; First body form is evaluated at compile time and must return a string.
  (concat "Toto is very " blabla ".")
  ;; Everything else is a regular lambda.
  (code using foo and bar (and blabla as well)))

Re: Constructed docstrings for closures

[Ted Zlatanov]

On Fri, 16 Jan 2015 11:18:26 -0500 Stefan Monnier <monnier@IRO.UMontreal.CA> wrote: 

SM> I'd like to lift this restriction by offering a new feature that lets us
SM> do something like:

SM>    (lambda (foo bar)
SM>      <something-magical-here>
SM>      (code using foo and bar (and blabla as well)))

SM> and get the closure we want with the docstring we want.

SM> Does anyone have an idea of what the <something-magical-here>
SM> could/should be?

Would it be crazy to make it look like a `defun' docstring?

    (lambda (foo bar)
      "My docstring about FOO and BAR"
      (code using foo and bar (and blabla as well)))

Ted

Re: Constructed docstrings for closures

[David Kastrup]

Ted Zlatanov <tzz@lifelogs.com> writes:

> On Fri, 16 Jan 2015 11:18:26 -0500 Stefan Monnier
> <monnier@IRO.UMontreal.CA> wrote:
>
> SM> I'd like to lift this restriction by offering a new feature that lets us
> SM> do something like:
>
> SM>    (lambda (foo bar)
> SM>      <something-magical-here>
> SM>      (code using foo and bar (and blabla as well)))
>
> SM> and get the closure we want with the docstring we want.
>
> SM> Does anyone have an idea of what the <something-magical-here>
> SM> could/should be?
>
> Would it be crazy to make it look like a `defun' docstring?
>
>     (lambda (foo bar)
>       "My docstring about FOO and BAR"
>       (code using foo and bar (and blabla as well)))

Uh, that one has worked for decades already.  The point was that the
docstring was to be _computed_ from a variable in the enclosing scope.

-- 
David Kastrup

Re: Constructed docstrings for closures

[Ted Zlatanov]

On Sun, 18 Jan 2015 13:19:25 +0100 David Kastrup <dak@gnu.org> wrote: 

DK> Ted Zlatanov <tzz@lifelogs.com> writes:
>> Would it be crazy to make it look like a `defun' docstring?
>> 
>> (lambda (foo bar)
>> "My docstring about FOO and BAR"
>> (code using foo and bar (and blabla as well)))

DK> Uh, that one has worked for decades already.  The point was that the
DK> docstring was to be _computed_ from a variable in the enclosing scope.

I had honestly never seen that in Emacs Lisp code, thanks for letting me
know (and sorry for the stupidity on my part). FWIW, I like Lars'
approach because it keeps things inside the lambda.

Ted