I am struggling with documenting my library. Do people duplicate their contracts from code to the documentation or am I missing something? scribble/srcdoc seems no to be used by (m)any (according to a code serach on github).

I struggle with the scribble language (I know LaTex and other markup languages) and I feel I spent a lot a time struggling with its syntax. I was wondering how to simplify this. Can one generate documentation from code in some way (at least as defproc stubs, with placeholders)?

At this point I do not want to spent the time to learn another language but rather concentrate on publishing my library. At the same time I do no want to ship without documentation.

I would appreciate any pointers or advice. Also tooling for e.g. emacs or DrRacket that would simplify the task of generating procdedure documentation

I duplicate the contracts. I think most people writes a separate scribble-document as documentation. I know some has experimented with inline documentation, but I don’t think it is widely used.

An example of a “contract” from what happens to be the last piece of documentation I write:

https://github.com/soegaard/sci/blob/master/flomat-doc/manual-flomat.scrbl#L930

The scribble syntax grows on you, but it does take a bit to get used to.

Yes, duplication is the usual approach.

If you really dislike duplication, you can use define/doc at https://github.com/greghendershott/frog/blob/master/frog/private/define-doc.rkt

Here’s how it’s used in action: https://github.com/greghendershott/frog/blob/master/frog/enhance-body.rkt#L18

One bad thing about this approach IIUC is that you can’t separate the actual library and the documentation. Installing the library will require one to also install the documentation.

whereas if you duplicate, you can put them in different packages (sigh)

@sorawee It’s “even worse” because define/doc also lets you supply snippets that are both examples and unit tests. So the thing where people make lib, doc, and test packages manually is even more at odds with this. It would be neat if such package splitting busywork could happen automatically from those kinds of submodules. In a hand-wavy way that seems plausible, but IIRC Matthew has said it would actually be pretty challenging to do.

@code Also, define/doc is just some code I wrote to use in Frog. You’re welcome to copypasta it, but I’m not offering it up as a package, and certainly not “evangelizing” it. :simple_smile:

A question about places: All this time I have been assuming that a thread running on one place can’t communicate with a thread running on another. Is that actually accurate in a shared-memory environment?

Hmmm, a relatively quick test appears to suggest not, since it seems that regular channels aren’t considered allowable in place messages, meaning that it’s awfully hard to provide threads on two different places a common channel to communicate on.

I’d be keen to hear if anyone has any suggestions on this :)

couldn’t they communicate via a place channel?

> To a first approximation, place channels support only immutable, transparent values as messages. In addition, place channels themselves can be sent across channels to establish new (possibly more direct) lines of communication in addition to any existing lines. The second sentence seems relevant?

It seems you could use place-channel to create that: https://docs.racket-lang.org/reference/places.html#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel%29%29 > (place-channel) → place-channel? place-channel? > > Returns two place channels. Data sent through the first channel can be received through the second channel, and data sent through the second channel can be received from the first. > > Typically, one place channel is used by the current place to send messages to a destination place; the other place channel is sent to the destination place (via an existing place channel).

(I don’t have any real mileage using places, so take this with a grain of salt.)

:thinking_face:

Essentially, what I have been doing is running threads ‘internally’ to a place, and the place itself handles the messaging via place channels, and handing those off to its internal threads via regular channels. Sort of a ‘two-layer’ system.

Thinking about it though, I think you’re both right that the threads could talk directly via place-channels themselves, regardless of which place they actually are sitting on. As in, each place still spins up its own threads, but if each one is given its own place-channel, it could still receive messages from any thread that has a reference to that channel.

I’ll have to look into this more when I get the chance.

Thanks @notjack and @greg :slightly_smiling_face:

I don’t think there’s necessarily anything wrong with the way you’re doing it, now. I thought you were asking for a way to do it “more directly” between the two threads, so, that’s what got me looking at the docs. Again, I don’t have any experience from which to suggest “oh this way might be better because of X”. Just trying to point out a possibility in case you prefer it.

Yeah, I was thinking about whether I could do have threads exchange messages in a ‘transparent’ way where they didn’t have to think about what place another thread was on. It looks like the “completely ignore it” approach doesn’t work, but replacing regular channels with place channels instead might do it. Of course, I’m not sure what the extra memory/computation cost of that could be.

The alternative would presumably be a way to assign every thread a global (to the program) ID prior to spinning everything up, having a way for places to figure out which place that ID lives under, sending it to the other place, and then the receiving place forwarding the message to the intended recipient.