Scribble: What is the right way to document a structure property?

Questions & Answers
1

I'm writing Scribble to document a struct type with an attached property and I'm unsure how to do it. Something like this:

(define-values (prop:foo foo-prop? foo-ref)
  (make-struct-type-property 'foo 'can-impersonate))
(struct person (name) #:property prop:foo (delay 7) #:transparent)
(person 'bob)
(force (foo-ref (person 'bob)))

When it comes time to document this, I might do something like this:

@defstruct*[foo ([name string?])]{A struct type for fooing.}
@defproc[(foo-ref ???) ???]{A func that gets the prop:foo from a struct.}
@defproc[(foo-prop? ???) boolean?]{A func that checks if something is a descriptor or instance of a struct type with prop:foo.}
@def???[prop:foo]{A structure property descriptor.}
2

Looking at the source code of the Racket Reference, you will see that these prop:... are documented with defthing. For instance:

@defthing[prop:procedure struct-type-property?]

I don’t usually see p-ref and p? being documented. These functions tend to be for internal uses and not exposed to users, so there is usually no need to document them. But if you do want to provide them to users, they would have the straightforward contracts:

p-ref :: p? -> <a contract recognizing whatever you store in the property>
p? :: any/c -> boolean?
2 Likes
3

Aha! Thank you very much.