mcfly: McFly Embedded API Documentation Runtime for Racket
Note: This is an alpha-quality release of the McFly runtime
package, since some other packages the author wants to release depend on this
one. This alpha release will also help detect any integration problems with
making PLaneT packages dependent on this runtime. The McFly Tools development
package, which helps a developer author packages using this runtime, might not
yet be available at the time you read this.
McFly began as a way for developers of reusable Racket packages to
embed API documentation in the source code of the package. One documentation
convenience is that McFly can reuse some information from the code in the
documentation, such as optionally getting procedure type informaion from some
contracts, and argument names from lambda forms.
McFly itself is actually implemented in two separate PLaneT packages: this package, mcfly
, on which packages that use McFly depend; and McFly Tools
, which provides raco
-based tools to help develop packages that use McFly, including things
not strictly documentation-related, such as maintaining PLaneT development
links based on information that is also used for documentation.
A package that uses McFly will typically include lots of (doc ...)
forms sprinkled throughout at least one of its Racket source code files. McFly is so-named due to users of McFly saying “doc” all the time.
The package will also generally have a few McFly-specific variables
added to its top info.rkt
The example file "main.rkt" below shows a use of McFly.
| (planet neil/mcfly))|
|(provide/contract (celsius->fahrenheit (-> number? number?))|
| (fahrenheit->celsius (-> number? number?)))|
|(doc (section "Introduction")|
| (para "This package provides procedures for temperature conversion. The Wikipedia entries for "|
| (hyperlink "http://en.wikipedia.org/wiki/Celsius"|
| " and "|
| (hyperlink "http://en.wikipedia.org/wiki/Fahrenheit"|
| " were used as authoritative references."))|
|(doc (section "Interface"))|
|(doc procedure celsius->fahrenheit|
| "Returns Celsius temperature "|
| (racket c-degrees)|
| " as Fahrenheit. For example:"|
| (racketinput (celsius->fahrenheit 0)|
| #,(racketresult 32))|
| "Celsius is named after the Swedish astronomer Anders Celsius. Sweden is historically part of the Vodka Belt, with high consumption of distilled beverages, and binge drinking. That is not to imply anything about validity of Swedish temperature units (cough, cough); just sayin'...")|
|(define (celsius->fahrenheit c-degrees)|
| (+ (* c-degrees 9/5) 32))|
|(doc procedure fahrenheit->celsius|
| "Returns Fahrenheit temperature "|
| (racket f-degrees)|
| " as Celsius. ``Fahrenheit'' starts with `F'. You know what else starts with `F'? "|
| (italic "Freedom")|
| ". That's right: "|
| (italic "America! Freedom! Freedom is the only way!"))|
|(define (fahrenheit->celsius f-degrees)|
| (* (- f-degrees 32) 5/9))|
| (#:planet 1:1 #:date "2000-01-02"|
| "Fixes Y2K bug.")|
| (#:planet 1:0 #:date "1997-08-29"|
| "Initial version. Judgment Day by Skynet."))|
When Scribble formats the documentation for the package of which this "main.rkt" is a part, the McFly runtime generates Scribble syntax from the doc forms in "main.rkt" and from metadata information in the corresponding "info.rkt" file. This constitutes a complete formatted manual for the
package. The package author does not typically edit a "*.scrbl" file. (McFly Tools generates a small "doc.scrbl" file that merely calls the McFly runtime to process "main.rkt" whenever Scribble goes to format the documentation. McFly Tools includes this generated "doc.scrbl" file when making the "*.plt" archive for upload to the PLaneT server.)
Note that the doc forms in "main.rkt" do not affect its normal compilation, and effectively are treated as comments. This is because (require (planet neil/mcfly)) imports a dummy doc syntax that merely transforms to an empty begin form.
The language of McFly is the doc form, as interpreted by the McFly runtime when formatting documentation.
|(doc procedure id pre-flow ...)|
|(doc history history-entry ...)|
|(doc scribble pre-flow ...)|
|(doc pre-flow ...)|
|history-entry|| ||=|| ||(maybe-version planet date pre-flow ...)|
| || || || || |
|maybe-version|| ||=|| |
| || ||||| ||#:version string|
| || || || || |
|planet|| ||=|| ||#:planet number-colon-number-symbol|
| || || || || |
|date|| ||=|| ||#:date yyyy-mm-dd-string|
Someday, this will be documented, but it’s pretty self-explanatory.
3 Known Issues
This alpha version of the McFly runtime has a number of known
issues (partly due to heavy reworking, on-and-off, as we learned more about
syntax objects and made some big design changes, without code cleanup) that we
have not yet gotten around to looking into:
Scribble is not linking identifiers. First assumption is that
some information used by Scribble, perhaps lexical context from the syntax
objects, is not preserved.
There is a kludge involving mcfly:para-if-pre-content that we’d like to get rid of.
The ability to infer information for turning (doc procedure ...) to defproc syntax is limited. Presently, McFly recognizes only a few forms,
such as define...lambda and provide/contract. lambda is handled pretty well. The only procedure contract combinator
handled at the moment is ->. The current internal representation and unification can support
some other things with few changes, but we have not yet gotten to it.
It could use better testing.
Copyright 2012 Neil Van Dyke. This program is Free Software; you can
redistribute it and/or modify it under the terms of the GNU Lesser General
Public License as published by the Free Software Foundation; either version
3 of the License,or (at your option) any later version. This program is
distributed in the hope that it will be useful, but without any warranty;
without even the implied warranty of merchantability or fitness for a
particular purpose. See http://www.gnu.org/licenses/ for details. For
other licenses and consulting, please contact the author.