What is the idiomatic way to write a “doc comment” in racket? I’ve been doing this:

;; foo bar baz ;; ;; Do the foo thing (define-metafunction ... foo : bar -> baz ...) but I bet there’s a more idiomatic way?

I’m not sure if you would call it idiomatic in the sense of “widely used”, but I think there are good examples in "<https://htdp.org/2021–5–4/Book/index.html|How to design programs>" (HtdP). Unfortunately, the explanation which parts might go into the comment and how/when to use them seem scattered across the book, but I can say I especially like the type signatures and use them for almost all of my functions. For a new edition I wish there was some textbox or appendix that summarized how to build the comments. My “interpretation” of the HtdP comments is https://git.sr.ht/~sschwarzer/todo-txt/tree/main/item/file/todo-txt/private/task.rkt\|here.

My impression is that most Racket code isn’t documented much. I’d like to see good examples where you consider the documentation good. :slightly_smiling_face:

Regarding the use of ;; vs. ; for the public API of a function vs. a following “internal” comment, I think it’s a good idea. (However, so far I haven’t really used it because paragraph formatting in the Vim plugin with such comments doesn’t work out of the box. That said, I think all that’s necessary is adding set comments+=;; to the .vimrc or equivalent configuration file.)

Oh my, I didn’t know this one, cool. I also just learned about *list/c and list*of

(Unrelated, but I like the idea that a promise can be contracted :smile: If only that were true in real life!)

https://docs.racket-lang.org/scribble/srcdoc.html#%28mod-path._scribble%2Fsrcdoc%29\|https://docs.racket-lang.org/scribble/srcdoc.html#%28mod-path._scribble%2Fsrcdoc%29

My impression is that most of the core lib is documented, and heavily used packages are. It’s all in scribble, so it’s separate, but the REPL or reasonable editor plugins can show it to you.

@sschwarzer you probably want to add an after/ftplugin for that, or check out vim-racket (or my fork of it)

+1 on the non-empty-listof - gonna have to switch to that. easier on the eyes.

what I was expecting was something like a “doc comment”— e.g., in elisp or python, you put a string inside the function as the first thing, etc. I don’t really care to follow the correct conventions in general though, that’s too much work :slightly_smiling_face:

There are no widely used “doc comment” system in place. I think, there have been experiments with a “doc comments” and having a tool that can extract them.

I guess insurance is kind of a contract for promises irl (but something that had better not to happen!)

I am finding that test-judgment-holds does not work as I expect! Compare these <https://github.com/dada-lang/dada-model/blob/a3fc7f3fde13d7bf9b7aa6a8a45f2b48cdca7787/racket/type-system.rkt#L169-L183|two examples>:

(redex-let* dada-type-system [env_empty ((def-init ()) (maybe-init ()) (vars ()))] (test-judgment-holds (expr-type program env_empty expr_let int env_empty)) ; this is an output! (test-judgment-holds (expr-type program env_empty expr_let int ((maybe-init ((s))) (def-init ((s))) (vars ((s (my String ()))))))) ; this is an output! As you can see, both calls to test-judgment-holds have different values for the output variables. If I type the value of env_empty in by-hand, I get an error. If I use a redex-let bound variable, it works (even though it is bound to the wrong value!)

I want to be able to write tests with a judgment that checks that the output terms are what I expect, but it seems like this is a bit tricky to do if I want to use redex-let to define various “subterms” that I can reference. Help!

After digging a little, I found this section on “inline documentation”: https://docs.racket-lang.org/scribble/srcdoc.html

(I admit that I foolishly search for “doc” on http://pkgs.racket-lang.org\|pkgs.racket-lang.org . I don’t know what I was expecting :slightly_smiling_face: )

“If your Racket program breaks, we’ll pay you a lump sum” :smile: I think the core team prefers to ensure a Racket program won’t break :wink:

This blog post explains how it is supposed to be used: https://blog.racket-lang.org/2012/06/submodules.html

Hi all, a package server question. Herbie allows packages to define Herbie plugins having a herbie-plugin key in their package description. It would be swell if we could search the package server for all packages with that key. Is that possible?

Is https://pkgs.racket-lang.org/pkgs-all.json.gz enough?

It would be nice if such tags could be added automatically, or at least suggested. “Your source code mentions <some-keyword>, would you like to add the tag <some-tag> to your package to ease its discovery?”

@soegaard2 ah—I really meant if this was a UI that was already built. Perhaps it could work as @laurent.orseau suggested, I don’t know… The thought was that we could list the active plugins in the Herbie UI and then have a link to “download more” that went to the this search.

We could built our own UI but realistically we will not, it’s not that high priority.

Maybe @jeapostrophe or @tonyg have suggestions?

It looks like define-runtime-module-path-based dependencies don’t show up in the circular imports error message (see thread).

For example, I just got this error: standard-module-name-resolver: cycle in loading at path: /Users/pavpan/herbie/src/programs.rkt paths: /Users/pavpan/herbie/src/programs.rkt /Users/pavpan/herbie/src/load-plugin.rkt context...: <cut>

So it looks like programs must import load-plugin which must import programs—that’s the only possible 2-cycle

But in fact, programs must import load-plugin which has a d-r-m-p dependency on bool which depends on plugin which depends on rules which depends on programs. This took forever to figure out.

Instead of using redex-let to define terms, try using define-term with names that don’t coincide with patterns (like empty-env instead of env_empty). I think test-judgment-holds is interpreting env_empty as a pattern (i.e. anything that matches an env) instead of what it’s bound by redex-let.

And as a general debugging note, if you find that a judgment holds where you don’t expect it to, you can use the second form of judgment-holds to get back what the output patterns are bound to, in order to see what’s happening. Or for even more information, use build-derivations (possibly with show-derivations) to see the full derivations tree. Although, sometimes that can be a bit overwhelming.

@ben.knoble I’m already using vim-racket. :slightly_smiling_face: What’s the URL for your fork?

@sschwarzer https://github.com/benknoble/vim-racket\|https://github.com/benknoble/vim-racket I believe

This is no longer the case. Any version of Racket now works fine

Using plot for the first time and wondering if there’s a simple way to either transform the x-axis labels (they are cardinal text values) or have them stagger in the y-direction so they don’t overlap?

Specifically for a discrete-histogram

perhaps plot-x-tick-label-angle would help?

https://docs.racket-lang.org/plot/params.html#%28def._%28%28lib._plot%2Fmain..rkt%29._plot-x-tick-label-angle%29%29

Thanks. Not sure how I missed that

Can you report that as a bug?

Thanks!

another thing that works: (side-condition any (equal? (term any) (term ...)))