suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: improve the documentation for generic interfaces (#3701)

Browse Source 
* doc: improve the documentation for generic interfaces

1. fix the doc on define/generic
2. make the use of `define/generic` necessary in the example code
This commit is contained in:
Fred Fu 2021-03-04 15:45:01 -05:00 committed by GitHub
parent 076426e796
commit 1484b35516
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 30 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
pkgs/racket-doc/scribblings/reference/generic.scrbl
View File

@ -146,15 +146,22 @@ Raised for @techlink{generic methods} that do not support the given
@defform[(define/generic local-id method-id)]{ @defform[(define/generic local-id method-id)]{
When used inside the method definitions associated with the When used inside the method definitions associated with the @racket[#:methods],
@racket[#:methods] keyword, binds @racket[local-id] to the generic for @racket[#:fallbacks], @racket[#:defaults] or @racket[#:fast-defaults] keywords,
@racket[method-id]. This form is useful for method specializations to binds @racket[local-id] to the generic for @racket[method-id]. This form is
use generic methods (as opposed to the local specialization) on other useful for method specializations to use generic methods (as opposed to the
values. local specialization) on other values.
Using the @racket[define/generic] form outside a @racket[#:methods] The @racket[define/generic] form is only allowed inside:
specification in @racket[struct] (or @racket[define-struct]) is an @itemlist[
syntax error.} @item{a @racket[#:methods] specification in @racket[struct] (or @racket[define-struct])}
@item{the specification of @racket[#:fallbacks], @racket[#:defaults] or
@racket[#:fast-defaults] in @racket[define-generics]}
]
Using @racket[define/generic] elsewhere is a syntax error.
}
@; Examples @; Examples
@ -178,6 +185,7 @@ syntax error.}
(define (gen-print s [port (current-output-port)]) (define (gen-print s [port (current-output-port)])
(fprintf port "String: ~a" s)) (fprintf port "String: ~a" s))
(define (gen-port-print port s) (define (gen-port-print port s)
@code:comment{we can call gen-print alternatively}
(super-print s port)) (super-print s port))
(define (gen-print* s [port (current-output-port)] (define (gen-print* s [port (current-output-port)]
#:width w #:height [h 0]) #:width w #:height [h 0])
@ -185,36 +193,39 @@ syntax error.}
(struct num (v) (struct num (v)
#:methods gen:printable #:methods gen:printable
[(define/generic super-print gen-print) [(define (gen-print n [port (current-output-port)])
(define (gen-print n [port (current-output-port)])
(fprintf port "Num: ~a" (num-v n))) (fprintf port "Num: ~a" (num-v n)))
(define (gen-port-print port n) (define (gen-port-print port n)
(super-print n port)) (gen-print n port))
(define (gen-print* n [port (current-output-port)] (define (gen-print* n [port (current-output-port)]
#:width w #:height [h 0]) #:width w #:height [h 0])
(fprintf port "Num (~ax~a): ~a" w h (num-v n)))]) (fprintf port "Num (~ax~a): ~a" w h (num-v n)))])
(struct bool (v) (struct string+num (v n)
#:methods gen:printable #:methods gen:printable
[(define/generic super-print gen-print) [(define/generic super-print gen-print)
(define/generic super-print* gen-print*)
(define (gen-print b [port (current-output-port)]) (define (gen-print b [port (current-output-port)])
(fprintf port "Bool: ~a" (super-print (string+num-v b) port)
(if (bool-v b) "Yes" "No"))) (fprintf port " ")
(super-print (string+num-n b) port))
(define (gen-port-print port b) (define (gen-port-print port b)
(super-print b port)) (gen-print b port))
(define (gen-print* b [port (current-output-port)] (define (gen-print* b [port (current-output-port)]
#:width w #:height [h 0]) #:width w #:height [h 0])
(fprintf port "Bool (~ax~a): ~a" w h (super-print* (string+num-v b) #:width w #:height h)
(if (bool-v b) "Yes" "No")))]) (fprintf port " ")
(super-print* (string+num-n b) #:width w #:height h))])
(define x (num 10)) (define x (num 10))
(gen-print x) (gen-print x)
(gen-port-print (current-output-port) x) (gen-port-print (current-output-port) x)
(gen-print* x #:width 100 #:height 90) (gen-print* x #:width 100 #:height 90)
(gen-print "Strings are printable too!") (define str "Strings are printable too!")
(gen-print str)
(define y (bool #t)) (define y (string+num str x))
(gen-print y) (gen-print y)
(gen-port-print (current-output-port) y) (gen-port-print (current-output-port) y)
(gen-print* y #:width 100 #:height 90) (gen-print* y #:width 100 #:height 90)