"Jakub T. Jankiewicz" <xxxxxx@onet.pl> writes:

> I personally don't see a reason to document something other then top level
> entities that you can access from REPL, like procedures, macros, and
> variables.

It makes sense to document libraries and procedure arguments too, but
the more important reason for expression-based documentation is
generality.

> In LIPS I've implemented same mechanism as in Emacs Lisp and Python. I don't
> see a reason for specific syntax for docstrings, as name suggests they should
> be strings.

One problem is that a Scheme interpreter may evaluate those strings,
which will have a performance impact. It's probably unnoticable, but not
ideal.

> In LIPS I have this syntax:
>
> (define (foo x)
>   "This is doc string"
>   (+ x x))

If the (+ x x) expression is removed, the return value is unclear. Will
the docstring be returned? Some implementations support procedures
without a body.

> (define-macro (foo x)
>   "This is doc string)
>   `(list ,x))
>
> Additionally when defining variables or hygienic macros doc string is at the
> end.
>
> (define foo 10 "this is doc string")

This goes against one of the requirements I posted earlier:
- No special forms or procedures for documenting different objects.

> (define-syntax foo (syntax-rules () ((_ x) x)) "this is doc string")

I think a more minimalistic, generalized form of docstrings is a better
fit for Scheme.

LIPS seems to do things similarly to Racket. The existing solutions
mentioned in the SRFI had different drawbacks, like limitations in what
sort of expressions could be documented, or having to add new arguments
to the classic (define ...) forms.

This was the only system I could think of that would avoid that and meet
the requirements, but I am happy to consider other suggestions.