Lassi Kortela <xxxxxx@lassi.io> writes:

> Here's a brain dump of where I stand on docstrings and related topics.
>
> (snip)
>
> It makes sense to encode text either for documentation purposes or for
> other purposes (e.g. writing it into a file as a web page). In each
> case the structure of the markup (if any) is identical. That means the
> same lexical syntax should be used in both cases. There should not be
> any special lexical syntax for documentation.
>
> It makes sense to have lexical syntax for text markup languages.
>
> A contrived example:
>
>   #markup("# Title
>
>            paragraph")

I disagree here. Markup languages are not Scheme, so they should not be
included/represented in syntax. If the user wants to specify how to
parse documentation text, they can do that using some sort of external
tool: a CLI flag, configuration file, library setting, etc.

> Documentation attached to a part of source code could go under the
> more general concept of declarations or metadata. Common Lisp and
> Emacs Lisp have declarations; Clojure has metadata. It could be argued
> that declarations are a kind of metadata. (Declarations are for the compiler and
> interpreter, whereas metadata is for the application, but I suspect the
> distinction would get muddy eventually.)

Yes, I purposely avoided this distinction. Gathering metadata would have
a performance impact, and adding the -g flag to include/strip debug
metadata adds more complexity. If a program wants to gather
documentation from a file, they should call a special (read) procedure,
called (read-doc).

> Common Lisp and Emacs Lisp have docstrings like so:
>
> (snip)
>
> In these languages, f a string literal is at the beginning of a function
> definition, it is considered a docstring. This works reasonably well, and I
> would advocate copying docstrings and declarations from Common Lisp into Scheme
> (with modest changes).

I replied to Jakub with the problems of this approach.

> If we had text markup literals, they could naturally be used in place of string
> literals to write documentation:
>
> (snip)
>
> It's not clear how to best represent a markup fragment as a Scheme
> object. It probably should not be a subtype of string.

I disagree with the characterization that this is "not general enough to
warrant a # character". I think a general documentation comment syntax
warrants a # character more than a specific #markup language would.

In my reply to Jakub's email I attempted to explain how this syntax
is more general and well-specified than the usual way of doing things
(whether its Emacs/CL/Clojure, the methods are similar).