On Sat, 25 May 2024 10:32:39 +0000
Antero Mejr <xxxxxx@antr.me> wrote:

> > (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.

If string is single expression in body it's handled as normal string (as
return value).

>
> 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.

Note that Most documentation system that exists for different languages only
document top level exported entities, if you want to document expressions
inside functions the tool that extract documentation will need to include all
the source code, otherwise the documentation will not make sense.

That's why for inner documentation you can use comments.

Also you don't need to use a different syntax to document arguments of a
function you can do this on function doc string level:

(define (foo x y)
  "(foo x y)

   x - this is a number
   y - this is a string"
   (+ x x))

You can use whatever syntax you want inside the string like Markdown or what
JavaScript is using with [JsDoc][1]. They use comments and at keywords like
@returns, and it also document public API, for nested expressions you can use
normal comments since they only make sense when you see the source code.

[1]: https://jsdoc.app/tags-example

--
Jakub T. Jankiewicz, Senior Front-End Developer
https://jcubic.pl/me
https://lips.js.org
https://koduj.org