[racket] How to read procedure documentation?

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>
> 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