Skip to content

Commit 87a1e58

Browse files
benknoblejeapostrophe
authored andcommitted
docs: link to wrapped make-cookie
This greatly aids traversing the documentation: readers of this module's make-cookie can now jump to the documentation of the wrapped function instead of jumping to net/cookies/server and scrolling or searching. One possible solution is to prefix the special name like "net:make-cookie": the only downside is that the link will display as "net:make-cookie" instead of "make-cookie"; see the GUI Easy documentation [1] as an example (e.g., "gui:dc<%>" in "Custom Views"). In that document, all racket/gui exports are prefixed with gui: to avoid ambiguity, and the links take you to the correct place within racket/gui documentation. That is accomplished by (require (for-label (prefix-in gui: racket/gui))) which I wanted to avoid here: I didn't want all references to net/cookies/server to use the net: prefix, and it is desirable for the docs to show "make-cookie". Thus instead we use a trick (by way of Sorawee and Matthew Flatt) to embed the require-for-label in a macro use [2]. [1]: https://docs.racket-lang.org/gui-easy/index.html [2]: https://github.com/racket/racket/blob/f2294a69784a5e77e83d8cf07d6cddab7f1b09fd/pkgs/racket-doc/syntax/scribblings/module-reader.scrbl#L10
1 parent 723fab4 commit 87a1e58

File tree

1 file changed

+8
-1
lines changed

1 file changed

+8
-1
lines changed

web-server-doc/web-server/scribblings/http.scrbl

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -454,6 +454,13 @@ transmission that the server @bold{will not catch}.}
454454
web-server/http/response-structs
455455
web-server/http/cookie))
456456

457+
@(begin
458+
(define-syntax-rule (define-from-net/cookies/server name export)
459+
(begin
460+
(require (for-label net/cookies/server))
461+
(define name @racket[export])))
462+
(define-from-net/cookies/server net:make-cookie make-cookie))
463+
457464
@(define rfc6265
458465
(hyperlink "https://tools.ietf.org/html/rfc6265.html"
459466
"RFC 6265"))
@@ -474,7 +481,7 @@ transmission that the server @bold{will not catch}.}
474481
cookie?]{
475482
Constructs a cookie with the appropriate fields.
476483

477-
This is a wrapper around @racket[make-cookie] from @racketmodname[net/cookies/server]
484+
This is a wrapper around @|net:make-cookie| from @racketmodname[net/cookies/server]
478485
for backwards compatibility. The @racket[comment] argument is ignored.
479486
If @racket[expires] is given as a string, it should match
480487
@link["https://tools.ietf.org/html/rfc7231#section-7.1.1.2"]{RFC 7231, Section 7.1.1.2},

0 commit comments

Comments
 (0)