Docstring as only form in a function

Docstring as only form in a function

[Arne Babenhauserheide]

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.


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.

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.


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.

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?


Best wishes,
Arne

Re: Docstring as only form in a function

[Neil Jerram]

On 2014-02-20 16:59, Arne Babenhauserheide wrote:
> 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.
> 
> 
> 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.

How does calling 'procedure-documentation' fit into this use case?  
Surely the most natural way, of reminding yourself what a 
not-yet-implemented function is supposed to do, is simply to look at its 
source code?

Regards,
       Neil

Re: Docstring as only form in a function

[Panicz Maciej Godek]

2014-02-20 17:59 GMT+01:00 Arne Babenhauserheide <arne_bab@web.de>:
> 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.

Re: Docstring as only form in a function

[Taylan Ulrich Bayırlı/Kammer]

Arne Babenhauserheide <arne_bab@web.de> writes:

> What do you think?

I don't have a strong opinion at all, since this feels like a bikesheddy
issue, but I think the current behavior is more preferable.  A lambda
form cannot have an empty body, and having a docstring shouldn't change
that, so I would expect (lambda x "foo") to be either an error, or yield
a constant function.  The former would deviate from the standards and
possibly make some code break (though it's a trivial fix), and is not an
improvement in consistency either since docstrings aren't mandatory.

Taylan

Re: Docstring as only form in a function

[Mark H Weaver]

Hi Arne,

Arne Babenhauserheide <arne_bab@web.de> writes:
> 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 agree with others that this is a very bad idea, and would encourage
you to change your habits.  However, for the sake of showing how easy it
is to modify 'define' to act the way you prefer in your own modules:

(define-syntax define
  (with-syntax ((guile-define #'(@ (guile) define)))
    (lambda (form)
      (syntax-case form ()
        ((define (name . args) str)
         (string? (syntax->datum #'str))
         #'(guile-define (name . args) str str))
        ((define . rest)
         #'(guile-define . rest))))))

     Mark