Vladimir Nikishkin <xxxxxx@gmail.com> writes:

> My question would be: why not use a homoiconic format rather than a
> specific lexical syntax for it?
> Say,
>
> ```
> (define (foo . o)
>   (comment "frobnicates a list of o")
>   (map frobnicate o ))
> ```

It's unclear what the comment attaches to. If it is documenting `foo`,
then how would you document `(map frobnicate o)`? Or nested procedures,
or modules? If you put another `(comment ... )` under, then you would
return the value of the expansion of `(comment ...)`. The provided
syntax is agnostic to the expression it is documenting.

Also `(comment ...)` would need to macro-expand (or run code), which
could change the behavior/performance of a program.

And brevity. You save the parens and identifier.

Here are the design requirements I was trying to meet. Perhaps it will
explain some of the decisions here.

- Must be able to attach documentation to any expression.
- Documentation syntax must be similar to existing syntax constructs.
- No special forms or procedures for documenting different objects.
- Syntax must not obstruct code readability or structural editing tools.
- In-source documentation must not be coupled to a specific markup language.
- Export formats must also be decoupled.
- Low minimum implementation burden.
- Negligible or zero runtime overhead.
- Provides an interface on which LSP and other editor tools can be built.