Documenting class fields

Questions & Answers
1

Hi,

What is the canonical way to document class fields in Scribble?

Consider for example the following code:

#lang typed/racket

(define my-class%
  (class object%
    (super-new)
    (init-field [public-integer : Integer])))

(define obj (new my-class% [public-integer 3]))
(set-field! public-integer obj 4)
(get-field public-integer obj)

How would I write a Scribble documentation entry for public-integer?

The obvious section 4.2.4 Documenting Classes and Interfaces does not seem to mention field documentation, and after a quick search in the class-rich GitHub - racket/gui I don't seem to find any examples.

Is it because publicly exposing fields is strongly discouraged? I don't see this message in the docs, but maybe I am missing something.

1 Like
2

Does @defthing[field-name #:kind "field"]{...} work? I think I may have used that before, and it rendered ok for me a quick experiment.

1 Like
3

Thank you for your suggestion @mflatt ! defthing almost works for me: the only missing detail is scoping. In my case, I want to document a field of a class which has the same name as a structure in the same module. More concretely, I am defining a class called dynamics% which has a field called network, and in the same module I define a structure called network, instances of which are supposed to be put into the field network of dynamics%.

I am currently looking into the implementation of defmethod, since it seems to solve the scoping issue, but I'd appreciate some additional pointers :slight_smile: