Inspecting bits and pieces that come my way I learned that there are no docstrings in Racket. One can write his docs with Scribble (how?), upload it online and even see the relevant docs in an IDE while hovering one's mouse cursor over the function name, for instance.
Suppose I want something like this without hosting the docs outside my project on GitHub. Is it possible?
I already asked Phind, and got a very satisfactory picture:
#lang racket
(require scribble/srcdoc)
(provide (all-defined-out))
(define/doc (add x y)
@doc["Adds two numbers together."]
(+ x y))
(define/doc (subtract x y)
@doc["Subtracts @racket[y] from @racket[x]."]
(- x y))
It doesn't work, of course, but as an illustration to my question it's quite satisfactory .
I have no particular experience with using the "self-documenting" functionality of Racket, yet, but the docs are great! I have used Scribble extensively for creating general internal documentation where I work.
Edit: I think you might find the @-syntaxquite illuminating. It is rather deeper than what I first thought when I first encountered it. It is used in Scribble, but can be used in general also, by using something like #lang at-exp racket at the top of your file.
Second Edit: I didn't really answer your question. Yes, you can host these docs locally, as far as I understand. One can install a package locally without it having to be published in general.
Doc-strings or not. It's somewhat of a question on culture. My impression is that some programmers that use doc-strings are tempted not write "proper" documentation.
They simply generate "documentation" automatically from the source code - which means there is no overview. No thought went into the order of how to present the concepts.
If you want "doc-strings" for your own code, a simple, solution is to add a strings
as the first expression in the body:
(define (add x y)
"The function `add` adds the numbers x and y."
(+ x y))
To see the "doc-string" place your cursor on top of an add identifier.
Then in racket-mode use use cmd-. to jump to the definition of add.
Use cmd-, to go back.
In DrRacket, right-click on the identifier and choose "jump to definition".
What editor do you mean? I'd be reasonably happy with either VScodium or with Emacs... With Vim, too, but I already know that it isn't familiar with Racket.
As @soegaard mentioned there's not really a culture of doing this, like there is in say Common Lisp and related langs like Emacs Lisp or Clojure.
Maybe partly why is that modules are more important in Racket, and so the conventional "unit of documentation" tends to be modules not individual functions; so you typically have a .scrbl per module?
Also the Racket culture is that User Guides are important, not just References. You only get the latter automagically from doc strings.
Anyway, I've tried using "doc strings" a little bit in some projects, to generate some "reference" items to be included in the usual Racket doc approach.
The scribble/srcdoc module provides some building blocks like proc-doc and proc-doc/names.
I found using these a little verbose. Also I wanted a way to supply examples that would also be run as tests. So:
I think it worked OK but I didn't come away with a passion to keep doing this (much less evangelize and/or turn the define/doc macro into a package I'd be obligated to support Forever ).
Not so! But if you prefer Vim and have questions on using it with Racket, please ask here or in Discourse. I wrote much of 24.3 Vim, and I should really update it now that some of the Racket files from my plugin are part of the Vim runtime distribution.
Ah! This isn't Vim for Racket, but the other way around, if I got it right .
I've been using AstroNvim, as the only prefabricated distribution which isn't just collapsing over your head. It's possible to add whatever plugin you wish without getting uncomfortably deep under the hood. It's Neovim, though.
I'm not the guy to write my own 4000 lines of configs to my perfect satisfaction
My mistake -- I got this message again at another link to the Racket site.
I read email with mutt in text-only mode.
It seems when I asked it to open the link in my browser I accidentally copied the
close-parenthesis after the URL in the Markdown-formatted link.
But the uncaught 404 exception does seem exceptional!
Check out my socks5 package for documented code with literate programming. Readme has rationale about why LP was a good fit. Code+docs in socks5.rkt. To browse rendered documentation, do raco pkg install socks5 and you can browse it locally.
.
.
.
).