"Docstrings" in Racket?

Question

I know Racket doesn't have "docstrings" in the same way that many other languages do, but given how convenient documenting things at the source is, I'd like to approximate something like it in Racket.

When I first learned about Scribble and #langs, I thought it would be possible to do something like:

#lang racket
#lang scribble

... and then write code in Racket with docstrings in Scribble. But this doesn't work, probably because "languages don't compose."

#lang racket
(require scribble/manual)

@racket['hi]

which results in:

my-source.rkt:4:0: @racket: unbound identifier

I came across scribble/srcdoc which seems compelling because it sounds like it allows you to piggyback docs on top of contracts which already serve as a kind of minimal (typically module-level) documentation, in addition to providing runtime checks of course. I haven't been able to get it to work so far, but instead of thrashing around for another several hours I thought it would be more useful to ask about it here. For what it's worth, here's what I'm seeing at the moment:

#lang racket
(require scribble/srcdoc
         (for-doc scribble/base scribble/manual))

(provide
 (proc-doc/names fib
                 (-> integer? integer?)
                 (n)
                 @{Computes the @racket[n]th Fibonacci number}))

(define (fib n)
  (if (< n 2)
      n
      (+ (fib (- n 1))
         (fib (- n 2)))))

which results in:

my-source.rkt:6:1: proc-doc/names: bad syntax
  in: (proc-doc/names fib (-> integer? integer?) (n) @ (Computes the @racket (n) th Fibonacci number))

Since reference docs like these are better at explaining how things work than how to use it, I'm looking for an answer that is more of a how-to on writing "docstrings" in Racket. It needn't be long, just sufficient to help the reader employ this "contract + docstring" pattern in their code (and, possibly, describing other alternatives).

Corporeity

I think scribble document is hard to understand. I just find a wrokable scribble file than learn how to use it. There are lot of detial can't answer in this post. You can learn it from scrbble file and html file. For example I see html have code block than I search all scrbl file with given keyword than I can understand how to use it. Than you can learn Title Content Refrence ... – Manolo

Makes sense, thanks for the field report @tjorchrt! Yeah, Scribble docs do seem to be more "reference" style than "guide" (unlike the Racket docs which have both). I did try to do something like what you're suggesting but scribble/srcdoc is maybe a less common approach so I wasn't able to find a lot of examples. – Corporeity

In case it's helpful to the next person, here's a blog post that contains some examples of contract-level "docstrings." – Corporeity

Related: #53938482 – Corporeity

Answer 1

You want the at-exp 'meta-language'. This lets you program in another language (in this case racket, with the modification of using at-expressions.

So taking your example above, you get:

#lang at-exp racket
(require scribble/srcdoc
         (for-doc scribble/base scribble/manual))

(provide
 (proc-doc/names fib
                 (-> integer? integer?)
                 (n)
                 @{Computes the @racket[n]th Fibonacci number}))

(define (fib n)
  (if (< n 2)
      n
      (+ (fib (- n 1))
         (fib (- n 2)))))

Note the at-exp in the first line.

You can also do:

#lang at-exp racket
(require scribble/manual)

@racket['hi]

and get:

(sized-element #f (list (cached-element #0=(style "RktVal" (list 'tt-chars (css-addition '(collects #"scribble" #"racket.css")) (tex-addition '(collects #"scribble" #"racket.tex")))) "'" ...) (cached-element #0# "hi" ...)) ...)

Cleromancy

That's really neat! How come the language is Racket, though, rather than Scribble, in the proc/doc example? Feels like it should be something like #lang racket to indicate the language of the file, and then #lang at-exp scribble to indicate which language to use in @ expressions? – Corporeity