Wolfgang Corcoran-Mathe <xxxxxx@sigwinch.xyz> writes:

> I’ve come to prefer the idea of
> documentation as a first-class identifier property rather than a
> “magic comment”, but I think this proposal might be able to bridge the
> two approaches. I also very much appreciate the “light” specification
> of the documentation format feature.

I think the two approaches are compatible: for implementations that
support identifier properties, attached documentation comments can be
parsed and put into an identifier property.

> I had difficulty with the notion of “attached” documentation as
> you’ve described it. What does it mean for ‘make-documentation’
> to take “an expression” as its *content* argument? In your example,
> you pass it the value ‘(+ 3 2), but the idea, of course, is to attach
> documentation to expressions, not values. (In other words, shouldn’t
> ‘documentation-object’ return a syntax object?) Maybe I’m missing
> something about how you’re expected to invoke these procedures.

The idea is to call (read-doc) to extract documentation from a
file/port, similar to how a REPL would call (read). When there are no
documentation comments, (read-doc) is the same as (read). When there
are, instead of returning an expression/object, (read-doc) returns a
documentation record, which wraps the expression/object along with the
text of the associated (or "attached") documentation comment. The
documentation comment must be "adjacent" to the expression/object in the
source code. Typically documentation comments would be placed
immediately before the expression, but I left the interpretation of
"adjacent" up to the implementation, based on feedback I received
earlier.

The documentation-content field is an unevaluated expression or readable
Scheme object, since R7RS-small does not have #'() syntax objects.

I think the code of doc-exporter.scm is a good example of how it is
intended to be used: it applies read-doc to a .scm/.sld file, and
exports formatted documentation to .txt files. Or maybe this snippet can
explain better:

```
(define code-from-scm-file "\
#|* Import the base and write libraries. *|#
(import (scheme base) (scheme write))

;; This expression has no documentation.
(define result (+ 3 2))

#|* Display the result of 3+2. *|#
(display result)

#|? Note: the answer should be five. ?|#
")

(define port (open-input-string code-from-scm-file))

(read-doc port)
=> documentation record
     attached = #t
     text = " Import the base and write libraries. "
     content = (import (scheme base) (scheme write))

(read-doc port)
=> (define result (+ 3 2))

(read-doc port)
=> documentation record
     attached = #t
     text = "  Display the result of 3+2. "
     content = (display result)

(read-doc port)
=> documentation record
     attached = #f
     text = "   Note: the answer should be five. "
     content = #f

(read-doc port)
=> eof-object
```