Skip to content

Commit

Permalink
docs: link to wrapped make-cookie
Browse files Browse the repository at this point in the history
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
  • Loading branch information
benknoble authored and jeapostrophe committed Apr 30, 2024
1 parent 723fab4 commit 87a1e58
Showing 1 changed file with 8 additions and 1 deletion.
9 changes: 8 additions & 1 deletion web-server-doc/web-server/scribblings/http.scrbl
Original file line number Diff line number Diff line change
Expand Up @@ -454,6 +454,13 @@ transmission that the server @bold{will not catch}.}
web-server/http/response-structs
web-server/http/cookie))

@(begin
(define-syntax-rule (define-from-net/cookies/server name export)
(begin
(require (for-label net/cookies/server))
(define name @racket[export])))
(define-from-net/cookies/server net:make-cookie make-cookie))

@(define rfc6265
(hyperlink "https://tools.ietf.org/html/rfc6265.html"
"RFC 6265"))
Expand All @@ -474,7 +481,7 @@ transmission that the server @bold{will not catch}.}
cookie?]{
Constructs a cookie with the appropriate fields.

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

0 comments on commit 87a1e58

Please sign in to comment.