►Mc  Fly Runtime:   Embedded Package Documentation for Racket
Mc  Fly Runtime:   Embedded Package Documentation for Racket
1 Introduction
1.1 Example
2 Interface
doc
3 Known Issues
4 History
5 Legal
2:2
  top  ← prev  up  next → 

McFly Runtime: Embedded Package Documentation for Racket

Neil Van Dyke

License: LGPLv3   Web: http://www.neilvandyke.org/racket/mcfly/
 (require mcfly) package: mcfly

1 Introduction

Note: This package of the McFly Runtime is transitional, to support moving packages from PLaneT to the new Racket package system. At time of this writing, a version of McFly Tools supporting the new package system is not distributed.
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 information from some contracts, and argument names from lambda forms.
McFly itself is actually implemented in two separate PLaneT packages: this package, McFly Runtime (aka PLaneT 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.

McFly is so-named due to users of McFly saying “doc” all the time.

A package that uses McFly will typically include lots of (doc ...) forms sprinkled throughout at least one of its Racket source code files. The package will also generally have a few McFly-specific variables added to its top "info.rkt" file.

1.1 Example

The example file "main.rkt" below shows a use of McFly.

"main.rkt"

#lang racket/base
 
(require mcfly
         racket/contract)
 
(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"
                      "Celsius")
           " and "
           (hyperlink "http://en.wikipedia.org/wiki/Fahrenheit"
                      "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.")
 
(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!"))
 
(define (fahrenheit->celsius f-degrees)
  (* (- f-degrees 32) 5/9))
 
(doc history
 
     (#: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, 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 typically does not edit any "*.scrbl" files. (McFly Tools generates a small "doc.scrbl" file that merely calls 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 mcfly) imports a dummy doc syntax that merely transforms to an empty begin form.
Although not shown in this example, as of McFly Runtime version 1:3, #lang at-exp is now supported, so you can now write your documentation like:

  @doc[procedure foo @para{This is a @italic{bar}.}]

in addition to:

  (doc procedure foo (para "This is a " (italic "bar") "."))

2 Interface

The language of McFly is the doc form, as interpreted by McFly Runtime when formatting documentation.

syntax

(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

Please contact the author with any feedback, to help identify issues and prioritize them.
This version of 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.

4 History

5 Legal

Copyright 2012, 2016 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.

  top  ← prev  up  next →