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.
____________________
Racket Users list:
http://lists.racket-lang.org/users
