[racket-dev] Documentation lacuna?

Jay, hello.

On 2013 Jan 21, at 16:12, Jay McCarthy <jay.mccarthy at gmail.com> wrote:

> I don't understand your concern.
> 
> The response structure, which is the only actual structure (everything
> else is an interface on it)...
> 
> a) Allows #f as the mime type

...but the documentation doesn't say what #f means here.  Does it mean 'dunno, you work it out', or 'there is no content', or 'use some default'? In fact it means "I promise there isn't any output, so so I don't have to tell you a MIME type", but that can only be discovered from experiment or inspecting the source.

> b) Has you provide an 'output' function that does the output. If you
> don't want there to be any output, then don't write any:
> 
> (response 304 #"304" (current-seconds) #f empty void)

When I read the documentation for RESPONSE, I thought 'oh dear, it doesn't know about no-content responses', because it reads as if it assumes (and implements) that every HTTP response has a message-body.  Reading "output produces the body" suggests that there's always supposed to be a body, especially because it seems to suggest that it _always_ produces a Content-Type header.  I don't think this is an outrageously wrong reading of the paragraph.

> So, what exactly is it that you want, if not what is already provided?

How about a second paragraph after "An HTTP response..." which reads:

> Certain HTTP responses (with status 1xx, 204 and 304) have no content.  These are correctly generated with a response structure which has #f for 'mime' and 'void' for 'output'.  Such responses have no message-body, and no content-length or content-type headers.

An alternative interface would be to have the response structure let output be (or/c false/c (-> output-port? void?)), and indicate that output:#f produces no output, ignores any MIME type and produces no Content-Type header.  That's potentially clearer (easier to guess the effect of) in the no-output case.

(response
  304 #"Not Modified"
  (current-seconds)
  #"IGNORED"
  (list (make-header #"Location" #"http://racket-lang.org/download"))
  #f)

Finally: Re-reading what I first wrote, I suspect I was becoming slightly fixated on response/full over response, which meant I was a good bit less clear than I should have been.  Sorry about that.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK