Is there anyone here using srcdoc ? It seems most, if not all in the racket world prefer out of source documentation. What’s the reasoning behind it, assuming that’s the case?

@pocmatos A couple of things have stood in the way of in-source documentation, in my experiences with Racket:

• Racket docs emphasize prose and descriptive text instead of structured information like what people put in tools like javadoc. This makes docs read more like manuals with detailed guides and terminology definitions, instead of a glossary of API bindings with types and one-line descriptions. Organizing docs like this is more like organizing a book, and the layout of a library’s doc module files is often entirely different from the layout of its implementation module files. This can make in-source documentation awkward to organize if the in-source docs are forced to reflect the structure of the implementation modules.
• Documentation is installed and rendered very seamlessly (and automatically for any package in the package catalog) with great editor and browser support, which means it’s pretty rare I need to look at a package’s source code at all. I have a vague feeling that a desire for in-source documentation sometimes stems from frustration that docs and code are separated with the code seen as authoritative - as in, what people look at first and rendered docs built from in-source comments are an afterthought hosted “somewhere else”. But if people strongly gravitate towards the docs to the point where prettified and hosted docs are often far easier to view than source code, the whole “in source documentation” thing becomes more about how a library author manages docs rather than about how library users interact with docs. Results in less motivation to work on the problem I think.
• Existing solutions for in-source docs seem lacking to me. They’re either too invasive requiring me to rewrite entire groups of modules, or they’re too inexpressive making their use more frustrating than separate modules. Sometimes they bring unwanted dependencies and restrictions on what languages and libraries can be used too.
• There’s so much other stuff to work on and not enough racketeers :)

I do think in-source docs are great for at least some parts of a library’s documentation and would like to see more experiments in that space.

Very interesting points. Allowing for a distinction between organization-of-explanation and organization-of-implementation sounds valuable.

@notjack Thanks for the great reply. That certainly seems to set the context.

@mflatt just to be sure I understand, the intended behavior is that if you pass unsafe-undefined as the argument to an optional position, it’s like it isn’t there

@samth Yes. For example, I had to change a test case for check-not-unsafe-undefined, because it was passing unsafe-undefined as an optional argument to the test harness.

DrRacket runs tests in the test submodule, but not tests in a test submodule of a submodule, for example:

#lang racket
(module+ test
  (displayln "DrRacket runs me"))

(module my-submodule racket
  (module+ test
    (displayln "but doesn’t run me")))

I want all tests to run, and my current solution is to add the following at the top level: (module+ test (require (submod ".." my-submodule test))). Is there a more principled approach, or a reason why this is a bad idea?

@robby Can you point me to where DrRacket draws its arrows in a text% field.

(I presume showing the results of make-traversal or something like that in the actual buffer.)

I say that because I would like to make a new racket:text% buffer that also has the arrows, if that’s possible anyway.

Also @dan might now?

I do see the docs for syncheck:add-arrow, but it doesn’t seem to say much about it.

drracket/private/syncheck/gui.rkt

Probably better to reuse that code instead of reimplement it

@robby Okay, thanks.

As I understand it though, that only defines a unit that expects the entire drracket tool, yes?

Like, as far as I can tell it expects the entire drracket tool, so I couldn’t just embed it in a larger snip. Yes?

I’m sorry, I don’t understand the question.

@notjack @pocmatos re: in-source docs, I would love to have them — just like tests, and for the same reasons. This was my first impression of module+ doc. I’d be disappointed to learn otherwise.

I think Perl POD had the right idea. Reference doc entries can go right next to the code — or not. There’s POD-only source files for user guides and other docs, and the master index can be searched from the command line.

Scribble does a lot more than POD, and sometimes it gets in the way. Take page breaks. When I don’t plan ahead, I’d rather (newpage) than break flow to twiddle titles.

Maybe I’m conflating “doc” with “spec.” The trifecta of responsibility: code, spec, test. Code does something. Spec tells human what code should do. Test tells machine what code should do. Types, as executable specs, do a little bit of both.

Having them all in one place is convenient.

anybody knows bfs dfs search code examples for graph data

https://paste.ee/p/WY4Vp