# Self-documented Racket source code **URL:** \ **Category:** Questions & Answers\ **Created:** [March 22, 2024, 11:53am UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820 "2024-03-22T11:53:12Z")\ **Posts on this page:** 13\ **Page:** 1
**Author:** ![Tyrn](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/tyrn/32/1731_2.png) [@Tyrn](https://racket.discourse.group/u/Tyrn)\ **Post date:** [March 22, 2024, 11:53am UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/1 "2024-03-22T11:53:12Z")
Hi, 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: ```scheme #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 😊 . ---
**Author:** ![bakgatviooldoos](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/bakgatviooldoos/32/1381_2.png) [@bakgatviooldoos](https://racket.discourse.group/u/bakgatviooldoos)\ **Post date:** [March 22, 2024, 11:56am UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/2 "2024-03-22T11:56:14Z")
Hi, @Tyrn. 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. There is even a section on [Literate Programming](https://docs.racket-lang.org/scribble/lp.html) 😁. Edit: I think you might find the `@-syntax` [quite illuminating](https://docs.racket-lang.org/scribble/reader.html). 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. ---
**Author:** ![soegaard](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/soegaard/32/19_2.png) [@soegaard](https://racket.discourse.group/u/soegaard)\ **Post date:** [March 22, 2024, 12:38pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/3 "2024-03-22T12:38:15Z")
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: ```scheme (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". ---
**Author:** ![Tyrn](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/tyrn/32/1731_2.png) [@Tyrn](https://racket.discourse.group/u/Tyrn)\ **Post date:** [March 22, 2024, 12:45pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/4 "2024-03-22T12:45:58Z")
> [@soegaard](#): > > Then in racket-mode use use cmd-. to jump to the definition of `add`. > Use cmd-, to go back. 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. ---
**Author:** ![bakgatviooldoos](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/bakgatviooldoos/32/1381_2.png) [@bakgatviooldoos](https://racket.discourse.group/u/bakgatviooldoos)\ **Post date:** [March 22, 2024, 12:50pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/5 "2024-03-22T12:50:33Z")
[The Bees Knees](https://docs.racket-lang.org/drracket/index.html) is what they mean :racket_heart:. Edit: I see, I spoke out of turn. Not an emacs enjoyer myself, but good to know! ---
**Author:** ![soegaard](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/soegaard/32/19_2.png) [@soegaard](https://racket.discourse.group/u/soegaard)\ **Post date:** [March 22, 2024, 12:52pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/6 "2024-03-22T12:52:59Z")
Either use DrRacket or Emacs. For Emacs use `racket-mode`. > **[Racket Mode](https://www.racket-mode.com/)** > > Racket Mode ---
**Author:** ![greghendershott](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/greghendershott/32/98_2.png) [@greghendershott](https://racket.discourse.group/u/greghendershott)\ **Post date:** [March 22, 2024, 1:30pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/7 "2024-03-22T13:30:41Z")
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`](https://docs.racket-lang.org/scribble/srcdoc.html#%28mod-path._scribble%2Fsrcdoc%29) 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 made a [`define/doc` macro](https://github.com/greghendershott/frog/blob/master/frog/private/define-doc.rkt). - [Example uses](https://github.com/greghendershott/frog/blob/master/frog/enhance-body.rkt). 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 😄). ---
**Author:** ![Tyrn](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/tyrn/32/1731_2.png) [@Tyrn](https://racket.discourse.group/u/Tyrn)\ **Post date:** [March 22, 2024, 1:58pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/8 "2024-03-22T13:58:19Z")
It doesn't show me anything new (VScodium, DrRacket). ---
**Author:** ![benknoble](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/benknoble/32/16_2.png) [@benknoble](https://racket.discourse.group/u/benknoble)\ **Post date:** [March 22, 2024, 3:48pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/9 "2024-03-22T15:48:41Z")
> [@Tyrn](#): > > it [Vim] isn't familiar with Racket. 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](https://docs.racket-lang.org/guide/Vim.html), and I should really update it now that some of the Racket files from my plugin are part of the Vim runtime distribution. ---
**Author:** ![Tyrn](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/tyrn/32/1731_2.png) [@Tyrn](https://racket.discourse.group/u/Tyrn)\ **Post date:** [March 22, 2024, 4:13pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/10 "2024-03-22T16:13:52Z")
Ah! This isn't Vim for Racket, but the other way around, if I got it right 😊 . I've been using [AstroNvim](https://astronvim.com/), 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 😇 ---
**Author:** ![hendrikboom3](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hendrikboom3/32/2748_2.png) [@hendrikboom3](https://racket.discourse.group/u/hendrikboom3)\ **Post date:** [March 23, 2024, 12:49pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/11 "2024-03-23T12:49:29Z")
> [The Bees Knees](https://docs.racket-lang.org/drracket/index.html) is what they mean :racket_heart:. > Going there gives me the following. Is this intentional? Page not found > ((uncaught-exception-handler) > (_(+(_)(_(+(_)(_)(_)(_)(_))(+(_)(_)(_)(_)(_))(+(_)(_)(_)(_))))(+(_)(_)(_)(\*)))) > uncaught exception: 404 ---
**Author:** ![hendrikboom3](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hendrikboom3/32/2748_2.png) [@hendrikboom3](https://racket.discourse.group/u/hendrikboom3)\ **Post date:** [March 23, 2024, 1:28pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/12 "2024-03-23T13:28:38Z")
> > [The Bees Knees](https://docs.racket-lang.org/drracket/index.html) is what they mean :racket_heart:. > > Going there gives me the following. Is this intentional? > > Page not found > > > ((uncaught-exception-handler) > > (_(+(_)(_(+(_)(_)(_)(_)(_))(+(_)(_)(_)(_)(_))(+(_)(_)(_)(_))))(+(_)(_)(_)(\*)))) > > uncaught exception: 404 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! -- hendrik ---
**Author:** ![cadence](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/cadence/32/998_2.png) [@cadence](https://racket.discourse.group/u/cadence)\ **Post date:** [May 8, 2024, 12:31pm UTC](https://racket.discourse.group/t/self-documented-racket-source-code/2820/13 "2024-05-08T12:31:36Z")
Check out my [socks5](https://github.com/cloudrac3r/racket-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.