[racket] Matthew's "doc-define.rkt"

Greg Hendershott wrote at 05/08/2014 08:45 PM:

Greg has some sensible points here, which I've also run into, and this 
is a topic once-dear to my heart, so I'll just comment IMHO on some details:

* I don't want names to get too terse.  Racket has been moving to a 
little more terse than RnRS Scheme over the years, but, for readability 
of the code to people new to it, I'd rather see "check" than "chk".  
(Or, in that particular case, "test"; see below.)

* Regarding "#::" (pound-colon-colon), I want to *reduce* 
cryptic-looking punctuation characters, and save the punctuation 
characters for big wins.  (This is also why my unreleased "#lang paddle" 
is almost exactly Racket, except for small tweaks I've been pleading for 
years in Racket, like ":foo" being equivalent to "#:foo".)  If it were a 
general type annotation syntax, I'd expect ":" or "::" rather than 
"#::"; for something specific to "defn", I'd rather see ":type", 
":contract", "#:type", "#:contract", or some keywordless integration 
with the "defn" syntax.

* Greg didn't say, but I think it's important to note that documentation 
annotations as part of a form that combines define/provide/document 
(perhaps with contract and/or type) should be shortcut for toplevel 
forms that can do the same thing. Sometimes you'll want to do the 
equivalent of a Scribble "defproc*" corresponding to multiple normal 
procedure "define" forms.  Other times, you'll have some procedures 
produced by a mini-language, without "define" forms appearing in your 
code for the procedures.

* I'd like a "#:test" or "#:tests" to simply be a shortcut for moving 
something to toplevel in a "module+ test", within a new "test-section" 
form of some kind.  Like in 
"http://www.neilvandyke.org/overeasy/#%28part._.Test_.Sections%29".

* Regarding "#:ex", I like the idea of having examples as part of the 
normal free-form narrative documentation prose, but have the option of 
having the expressions checked statically, to make sure that they're 
(still) correct.  Examples in the free-form, rather than in a special 
``Examples'' part of, say, a "defproc", is also consistent with most 
existing Racket package docs I've seen.

* Side comment: when I was implementing McFly, and wanting to reduce 
redundant source text by having it optionally infer documentation 
signatures for a name based on contract or "lambda" signatures, and then 
I looked at Typed Racket (which wasn't ready at the time, missing 
keyword arguments or something, and also more angry-looking at the 
time)... and at the myriad different contract forms... I decided there 
was just *too much stuff*, and to stop using contracts and to stop 
implementing any more documentation inference.  So, when I document a 
procedure in my recent Racket libraries, I'm specifying the procedure 
signature twice, in two different ways, usually for no good reason.  But 
it's better than being roped into too-much-stuff, or into dumbed-down; 
more like biding my time till there is a obvious better way to do it 
long-term.  (My Meow Emacs mode will have special support for McFly, 
like Quack does for Funcelit.)

BTW, I've been chasing after Racket embedded documentation for about 13 
years now.  I first wrote the Texinfo-based Funcelit (``functionally 
illiterate programming'') embedded documentation stuff for Scheme, which 
made very nice typeset PS and PDF files, and passable HTML ones.  Then I 
made a special converter from Funcelit to Racket's "doc.txt" of the 
time.  And generating PLaneT packages. And HTML docs in Racket 
packages.  And then Racket JS search indexes, when Eli added that.  
Then, when Scribble came out, I wrote a generator from Funcelit to 
that.  But Funcelit's Texinfo base wasn't nearly as expressive as 
Scribble for types, and I wanted to support Racket better, so I bit the 
bullet and made McFly ("http://www.neilvandyke.org/mcfly/", which ended 
up involving both embedded documentation, and general package definition 
facilities for a particular reuse school of thought).  McFly 
documentation isn't as readable in source code as Funcelit was (partly 
because it's saying more), but it's more Racket-friendly.  I slowly 
converted my old packages to McFly, and almost finished with that 
("http://www.neilvandyke.org/racket/").  Then the next thing to chase 
became the new package system, since McFly is necessarily tied to PLaneT 
for some things at the moment, and I'd have to yet again go back to my 
embedded documentation tools and rethink&reimplement those parts.  (But 
I also don't want to give up multiple-installed-version package support, 
which has seemed to be an important part of a reuse discipline I was 
working on for my book, so that's another reason for wait-and-see.)  
Occasionally, during breaks between chasing after Racket changes for 
tools changes, I find time to make non-tools stuff that uses Racket.

Neil V.