Re: Docstring as only form in a function

[Panicz Maciej Godek]

2014-02-20 17:59 GMT+01:00 Arne Babenhauserheide <address@hidden>:
> Hi,
>
> I recently experimented with docstrings, and I stumbled over not being
> able to define a function which only has a docstring as body:
>
>
>     (define (foo)
>       "bar")
>
>     (procedure-documentation foo)
>     => #f
>
> Adding a form makes the string act as docstring:
>
>     (define (foo)
>       "bar"
>       #f)
>
>     (procedure-documentation foo)
>     => "bar"
>
> I feel that this is inconsistent, which hurts even more, because it
> breaks for the simplest showcase of docstrings.

I feel that this is the desired behaviour. According to the semantics of Scheme,

(define (foo)
  "bar")

defines a thunk that evaluates to "bar". This makes a lot of sense,
and modifying that behaviour would be very surprising.

> My use case for using docstrings like this is that when I start writing
> a function, I begin with the docstring. There I explain what I want to
> do. Then I commit. Then I implement the function.

So you can either do

(define (new-foo)
  "function that baz the bar"
  #f)

or even better,

(define (new-foo)
  "function that baz the bar"
  (throw 'not-implemented))

> We already discussed in #guile @ freenode, that it is simple to add a
> dummy-body to make the docstring work. To me that feels like a
> cludge. And I was asked to move the discussion here.

This would completely reverse the priorities. For the evaluator, it's
the value of an expression that is important, and a docstring is
something optional. It would be very misleading to have a function
that has a docstring but has no body. Note that this is illegal:

(define (dummy-function))

On the other hand, a function that only returns a string is rather
trivial and hardly needs a documentation.

> A reason for not wanting a string as the only part of the body to be
> seen as docstring are that this would make it harder to write
> functions which only return a string without giving them their return
> value as docstring. This would then require this:
>
>     (define (foo)
>       #f
>       "bar")
>
>
> I think it would be more consistent to have the first form of the body
> double as a docstring if it is a string.

I don't see any point in this. In a real program you'll never have
anything like that:
(define (a-very-self-descriptive-function)
  "this is a function that returns this string, and besides does nothing else")

If function stubs are to be the only argument, then I'd rather suggest
you to change your habits. Also, if you really need to provide a
docsting for a function that only returns a string, it would be much
better to do:

(define (a-function-that-returns-a-string-foo)
  "this function returns a string 'foo'"
  "foo")

Your suggestion smells like a dirty hack, and the only motivation is
to provide a documentation for functions that have no bodies -- which
is wrong.

> The current behaviour is that if the first form in the function is a
> string, it is not part of the body - except if the body would
> otherwise be empty.
>
>
> What do you think?

I oppose. That would be very misleading and it makes no sense in real
(or ready) programs.

Best regards,
M.