[racket] How to read procedure documentation?

Also see proc-doc and friends for a "creator 3" possibility!

Robby

On Saturday, April 20, 2013, Matthias Felleisen wrote:

>
> Creator 1: Sure enough this was a miscommunication. The creator of
> file->string added the check in the its implementation and then used the
> check to document the function. If the check is inside the function, as is
> the case here, there is no cross-checking between the docs and the code.
>
> Creator 2: However, Racket provides a contract system. If the creator of
> file->string had used it, he would have done it this way:
>
>  (provide
>    (contract-out
>      (file->string (-> path-string? string?))))
>
> and in principle, we could then have documented the function straight from
> this export statement, meaning the documentation and the code would be in
> sync.
>
> People who act like creator 1 tend to write docs as if they had acted like
> creator 2, writing docs as if you had used the contract system. Even if you
> are a creator 2 kind of person, you may manually create the docs with a
> copy of the contract instead of linking it directly to the contract.
> (Java's doc system kind of forces the reuse of types in the docs, so we're
> a step down from there in this regard.)
>
> -- Matthias
>
>
>
>
>
> On Apr 20, 2013, at 10:40 AM, Manfred Lotz wrote:
>
> > On Sat, 20 Apr 2013 10:19:54 -0400
> > Matthias Felleisen <matthias at ccs.neu.edu <javascript:;>>
> > wrote:
> >
> >>
> >> On Apr 20, 2013, at 12:37 AM, Manfred Lotz wrote:
> >>
> >>> My understanding is that parameter path-string? will be
> >>> checked at run time but only if the programmer who coded e.g.
> >>> file->string did call path-string?.
> >>
> >>
> >> No, the function will check pathness. Try file->string with a string
> >> that contains \0.
> >
> > Either I did not understand or I just did not express myself correctly.
> >
> > file->string uses file->x
> >
> >  (define (file->string f #:mode [mode 'binary])
> >    (file->x 'file->string f mode read-string string-append))
> >  .....
> > and file->x
> >
> >  (define (file->x who f file-mode read-x x-append)
> >    (check-path who f)
> >  .....
> >
> > checks explicitly for path-string? via check-path
> >
> >  (define (check-path who f)
> >    (unless (path-string? f)
> >      (raise-argument-error who "path-string?" f)))
> >
> >
> > If the programmer would have forgotten to code check-path in file->x
> > then there would be no check. Therefore my understanding is that the
> > language itself cannot enforce the predicate (as it has not a type
> > system like Haskell or Ocaml). This is that enforcement of the
> > predicate relies on proper programming.
> >
> > Or did I miss anything?
> >
> >
> > --
> > Manfred
> >
> >
> >
> >
> >
> >
> >
> > ____________________
> >  Racket Users list:
> >  http://lists.racket-lang.org/users
>
>
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20130420/573f54d7/attachment.html>