[racket-dev] Scribble in-source documentation documentation

From: Norman Gray (norman at astro.gla.ac.uk)
Date: Sat Jun 26 15:47:24 EDT 2010


Section 4.5 of the Scribble docs, 'In-Source Documentation' refers to the file/gif.rkt source as a useful example of this practice.  However, probably due to version changes, that file now looks different from what's described in the section it purportedly exemplifies.

Namely (noting docs -> gif.rkt):

  * '#reader scribble/reader' -> '#lang at-exp scheme/base'

  * '(require/doc scribble/base scribble/manual)' -> '(require/doc scheme/base scribble/manual)'


Separately, the documentation for proc-doc/names shows the structure of the form as

    (proc-doc/names id contract ((arg-id ...) ((arg-id default-expr) ...)) desc-expr)

I read that as requiring two subforms within the third proc-doc/names argument, even if there are zero (arg-id default-expr) forms.  Thus this seems to suggest that a procedure with one mandatory and no optional arguments would be declared as 

    (proc-doc/names foo (-> type type) ((arg1) ()) @{Description})

I appreciate there isn't really a formal grammar here, but adding a further exemplar line without the default-expr forms might be clearer -- is there perhaps a missing template

    (proc-doc/names id contract (arg-id ...) desc-expr)

As it was, it took some grepping through collects/* before I worked out why I was getting errors with my first attempt (no tragedy, of course, but it slows one down...).


Separately (again), the discussion in section 4.5.2 might benefit from some attention.  The description of provide-extracted mentions that "the documentation is packaged and exported as exported, instead of left inline."  I think I can see the intention here, but the phrase 'exported as exported' seems terribly important without being at all transparent as to meaning.  This paragraph suggests that provide-extracted should go in the scribble file, while the next one seems to suggest that it should instead go in the module file.  Then I look around and find framework/main.scrbl, which refers to main-extracts.ss, and ... I'm starting to get a bit confused.  I think I may now see which (third!) file the provide-extracted form should go into, but it's definitely getting a bit voodoo, now.

I can't just flail around and experiment, because the module I'm trying to document doesn't appear to work in an expected way with include-extracted.  In my scribble file I have 

% cat rdf.scrbl
#lang scribble/manual
@(require scribble/extract)
@title{The rdf library, wrapping librdf.org}
If you give a mouse a cookie, he's going to ask for a glass of milk.
@(include-extracted "../src/build/rdf.ss")

In the rdf.ss I have a line '(require "librdf-extn.rkt")', and in ../src/build I have rdf.ss and compiled/native/i386-macosx/3m/librdf-extn_rkt.dylib (ie, an extension, with no associated .rkt or .ss file).  Running scribble then gives:

% scribble --html rdf.scrbl
default-load-handler: cannot open input file: "/checkouts/me/code/plt-librdf/doc/librdf-extn.rkt" (No such file or directory; errno=2)

 === context ===
/Data/LocalApplications/Racket/Racket v5.0/collects/racket/private/map.rkt:18:11: map
/Data/LocalApplications/Racket/Racket v5.0/collects/scribble/run.rkt: [running body]
% pwd

That is, the processing of include-extracted seems to be searching for required modules in an unexpected way.

Thanks for any illumination.  Best wishes,


Norman Gray  :  http://nxg.me.uk

Posted on the dev mailing list.