Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
I'll try to make a small example collection.
Ok, I've narrowed the bug down. It's something with the use of
`defform*'. Attached is a patch that creates a `ts' collection. If
you apply it, and then do the following:
% raco setup ts
% cd collects/ts
% racket test-docs-complete.rkt
ts/scheme has undocumented exports:
(x1)
You see the problem. The relevant use of `defform*' is:
@defform*[#:id x1 [(qqq x1)]]
Basically any change to this removes the bug, for example, moving the
`qqq' *after* `x1' causes the bug to go away.
What should I run that's lower-level than `check-docs' to see if the
problem is there?
--
sam th
sa...@ccs.neu.edu
From 81b873954b0529decdddb23eb54ec2098d2a7f74 Mon Sep 17 00:00:00 2001
From: Sam Tobin-Hochstadt sa...@racket-lang.org
Date: Sun, 26 Jun 2011 10:01:39 -0400
Subject: [PATCH] demo bug
---
collects/ts/b.rkt |5 +
collects/ts/doc.scrbl |8
collects/ts/info.rkt |2 ++
collects/ts/racket.rkt |3 +++
collects/ts/scheme.rkt |3 +++
collects/ts/test-docs-complete.rkt |4
6 files changed, 25 insertions(+), 0 deletions(-)
create mode 100644 collects/ts/b.rkt
create mode 100644 collects/ts/doc.scrbl
create mode 100644 collects/ts/info.rkt
create mode 100644 collects/ts/racket.rkt
create mode 100644 collects/ts/scheme.rkt
create mode 100644 collects/ts/test-docs-complete.rkt
diff --git a/collects/ts/b.rkt b/collects/ts/b.rkt
new file mode 100644
index 000..1d8da33
--- /dev/null
+++ b/collects/ts/b.rkt
@@ -0,0 +1,5 @@
+#lang racket/base
+(require (for-syntax racket/base))
+(define-syntax x1 #f)
+(define-syntax x2 #f)
+(provide (all-defined-out))
diff --git a/collects/ts/doc.scrbl b/collects/ts/doc.scrbl
new file mode 100644
index 000..0fecc26
--- /dev/null
+++ b/collects/ts/doc.scrbl
@@ -0,0 +1,8 @@
+#lang scribble/manual
+@(require (for-label ts/racket))
+@title{T}
+@(defmodulelang* (ts/racket) #:use-sources (ts/b))
+@defform*[#:id x1 [(qqq x1)]]
+@defform[(x2)]
+@section{S}
+@(defmodulelang* (ts/scheme) #:use-sources (ts/b))
diff --git a/collects/ts/info.rkt b/collects/ts/info.rkt
new file mode 100644
index 000..870d7a1
--- /dev/null
+++ b/collects/ts/info.rkt
@@ -0,0 +1,2 @@
+#lang setup/infotab
+(define scribblings '((doc.scrbl () (language
diff --git a/collects/ts/racket.rkt b/collects/ts/racket.rkt
new file mode 100644
index 000..e46bf95
--- /dev/null
+++ b/collects/ts/racket.rkt
@@ -0,0 +1,3 @@
+#lang racket
+(require ts/b)
+(provide (all-from-out ts/b))
diff --git a/collects/ts/scheme.rkt b/collects/ts/scheme.rkt
new file mode 100644
index 000..e46bf95
--- /dev/null
+++ b/collects/ts/scheme.rkt
@@ -0,0 +1,3 @@
+#lang racket
+(require ts/b)
+(provide (all-from-out ts/b))
diff --git a/collects/ts/test-docs-complete.rkt b/collects/ts/test-docs-complete.rkt
new file mode 100644
index 000..97fd52c
--- /dev/null
+++ b/collects/ts/test-docs-complete.rkt
@@ -0,0 +1,4 @@
+#lang racket/base
+(require rackunit/docs-complete)
+(check-docs (quote ts/scheme))
+(check-docs (quote ts/racket))
--
1.7.4.1
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
On Thu, Jun 23, 2011 at 9:51 PM, Robby Findler ro...@eecs.northwestern.edu wrote: So I think the fix is to do the renaming for with-handlers before it gets exported from typed-scheme/base-env/prims (or introduce another module and put that one in the #:use-sources and use it as the one where the re-providing is happening). Ok, I did this, and it worked nicely. Thanks! Unfortunately, the issue with `-' seems to be different. In particular, `-' in `typed/scheme' and in `typed/racket' are both defined in typed-scheme/base-env/base-types-extra.rkt, under the name `-', and it isn't renamed in between. Other identifiers, such as `U', are defined in the same place, and treated identically, but the docs for `U' work just fine. -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
I'm not seeing something wrong. Maybe it would help if you could make a smaller example. Robby On Sat, Jun 25, 2011 at 8:15 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: On Thu, Jun 23, 2011 at 9:51 PM, Robby Findler ro...@eecs.northwestern.edu wrote: So I think the fix is to do the renaming for with-handlers before it gets exported from typed-scheme/base-env/prims (or introduce another module and put that one in the #:use-sources and use it as the one where the re-providing is happening). Ok, I did this, and it worked nicely. Thanks! Unfortunately, the issue with `-' seems to be different. In particular, `-' in `typed/scheme' and in `typed/racket' are both defined in typed-scheme/base-env/base-types-extra.rkt, under the name `-', and it isn't renamed in between. Other identifiers, such as `U', are defined in the same place, and treated identically, but the docs for `U' work just fine. -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
What's wrong is that for typed/scheme check-docs thinks that - is undocumented, even though it's able to find the docs for the same identifier provided from typed/racket. It's the same problem as with with-handlers, but if appears not to have the same cause. On Jun 24, 2011 8:53 PM, Robby Findler ro...@eecs.northwestern.edu wrote: I'm not seeing something wrong. Maybe it would help if you could make a smaller example. Robby On Sat, Jun 25, 2011 at 8:15 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: On Thu, Jun 23, 2011 at 9:51 PM, Robby Findler ro...@eecs.northwestern.edu wrote: So I think the fix is to do the renaming for with-handlers before it gets exported from typed-scheme/base-env/prims (or introduce another module and put that one in the #:use-sources and use it as the one where the re-providing is happening). Ok, I did this, and it worked nicely. Thanks! Unfortunately, the issue with `-' seems to be different. In particular, `-' in `typed/scheme' and in `typed/racket' are both defined in typed-scheme/base-env/base-types-extra.rkt, under the name `-', and it isn't renamed in between. Other identifiers, such as `U', are defined in the same place, and treated identically, but the docs for `U' work just fine. -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
What I meant is that I don't see what is wrong with your code, not that I don't see check-docs complaining. On Sat, Jun 25, 2011 at 9:14 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: What's wrong is that for typed/scheme check-docs thinks that - is undocumented, even though it's able to find the docs for the same identifier provided from typed/racket. It's the same problem as with with-handlers, but if appears not to have the same cause. On Jun 24, 2011 8:53 PM, Robby Findler ro...@eecs.northwestern.edu wrote: I'm not seeing something wrong. Maybe it would help if you could make a smaller example. Robby On Sat, Jun 25, 2011 at 8:15 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: On Thu, Jun 23, 2011 at 9:51 PM, Robby Findler ro...@eecs.northwestern.edu wrote: So I think the fix is to do the renaming for with-handlers before it gets exported from typed-scheme/base-env/prims (or introduce another module and put that one in the #:use-sources and use it as the one where the re-providing is happening). Ok, I did this, and it worked nicely. Thanks! Unfortunately, the issue with `-' seems to be different. In particular, `-' in `typed/scheme' and in `typed/racket' are both defined in typed-scheme/base-env/base-types-extra.rkt, under the name `-', and it isn't renamed in between. Other identifiers, such as `U', are defined in the same place, and treated identically, but the docs for `U' work just fine. -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
Ah, I see. Well, that makes two of us. I'll try to make a small example collection. On Fri, Jun 24, 2011 at 9:46 PM, Robby Findler ro...@eecs.northwestern.edu wrote: What I meant is that I don't see what is wrong with your code, not that I don't see check-docs complaining. On Sat, Jun 25, 2011 at 9:14 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: What's wrong is that for typed/scheme check-docs thinks that - is undocumented, even though it's able to find the docs for the same identifier provided from typed/racket. It's the same problem as with with-handlers, but if appears not to have the same cause. On Jun 24, 2011 8:53 PM, Robby Findler ro...@eecs.northwestern.edu wrote: I'm not seeing something wrong. Maybe it would help if you could make a smaller example. Robby On Sat, Jun 25, 2011 at 8:15 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: On Thu, Jun 23, 2011 at 9:51 PM, Robby Findler ro...@eecs.northwestern.edu wrote: So I think the fix is to do the renaming for with-handlers before it gets exported from typed-scheme/base-env/prims (or introduce another module and put that one in the #:use-sources and use it as the one where the re-providing is happening). Ok, I did this, and it worked nicely. Thanks! Unfortunately, the issue with `-' seems to be different. In particular, `-' in `typed/scheme' and in `typed/racket' are both defined in typed-scheme/base-env/base-types-extra.rkt, under the name `-', and it isn't renamed in between. Other identifiers, such as `U', are defined in the same place, and treated identically, but the docs for `U' work just fine. -- sam th sa...@ccs.neu.edu -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
Thanks. I think that'll help us figure out where the problem is. Robby On Sat, Jun 25, 2011 at 9:54 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: Ah, I see. Well, that makes two of us. I'll try to make a small example collection. On Fri, Jun 24, 2011 at 9:46 PM, Robby Findler ro...@eecs.northwestern.edu wrote: What I meant is that I don't see what is wrong with your code, not that I don't see check-docs complaining. On Sat, Jun 25, 2011 at 9:14 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: What's wrong is that for typed/scheme check-docs thinks that - is undocumented, even though it's able to find the docs for the same identifier provided from typed/racket. It's the same problem as with with-handlers, but if appears not to have the same cause. On Jun 24, 2011 8:53 PM, Robby Findler ro...@eecs.northwestern.edu wrote: I'm not seeing something wrong. Maybe it would help if you could make a smaller example. Robby On Sat, Jun 25, 2011 at 8:15 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: On Thu, Jun 23, 2011 at 9:51 PM, Robby Findler ro...@eecs.northwestern.edu wrote: So I think the fix is to do the renaming for with-handlers before it gets exported from typed-scheme/base-env/prims (or introduce another module and put that one in the #:use-sources and use it as the one where the re-providing is happening). Ok, I did this, and it worked nicely. Thanks! Unfortunately, the issue with `-' seems to be different. In particular, `-' in `typed/scheme' and in `typed/racket' are both defined in typed-scheme/base-env/base-types-extra.rkt, under the name `-', and it isn't renamed in between. Other identifiers, such as `U', are defined in the same place, and treated identically, but the docs for `U' work just fine. -- sam th sa...@ccs.neu.edu -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
On Wed, Jun 22, 2011 at 6:53 PM, Robby Findler ro...@eecs.northwestern.edu wrote: To really know what is going on, one has to trace thru the re-provides for each of these identifiers and match them up to the declare-exporting declarations. In the declaration below, you're essentially saying any identifiers documented in this module should appear to come from the typed/scheme/base, typed/scheme, and typed-scheme modules, but they are really actually exported from one of the modules listed in the #:use-sources keyword which means, to the documentation system that any module that re-exports an identifier from, say, typed-scheme/base-env/base-types-extra, will have its documentation attached to the docs in the file with the declare-exporting below and the docs system will then point userse to typed/scheme/base. I don't think that this is what you want, since you probably want to to point people to typed/racket. That's not what's going on here, although you couldn't tell that from my email. That `declare-exporting' is in a subsection which only documents `typed/scheme' etc, and not any of the actual forms in Typed Racket. To know what the right answer is for the declare-exporting below, I'd have to know how typed/racket fits into the picture. In particular, is it re-exporting things from typed/scheme? Or from those helper modules you have listed? Or from some other place? It's probably easier to just consider `typed/racket/base' and `typed/scheme/base' here. Both of them export identifiers from the modules listed in the `declare-exporting' declaration. For example, `with-handlers' is defined in `typed-scheme/base-env/prims'. Here's what the documentation for `typed/racket/base' looks like: @(defmodulelang* (typed/racket/base typed/racket) #:use-sources (typed-scheme/typed-scheme typed-scheme/base-env/prims typed-scheme/base-env/extra-procs typed-scheme/base-env/base-types typed-scheme/base-env/base-types-extra)) Also, I don't think this is a problem with the general setup of documentation for Typed Racket. In particular, the identifier `define-type' is defined in the same module as `with-handlers', and it gets handled properly by Scribble, by DrRacket, and by `check-docs'. You can see this by searching for `define-type' in the documentation, or for `U', which is defined in the same module as `-'. Instead, I think the problem is that `with-handlers' and `-' are both identifiers exported from `racket', and this is causing some sort of confusion in the Scribble doc system, but I don't know exactly what, and I'm therefore confused about how to try to fix it. Of course, it might be something totally different, also -- the vagaries of Scribble linking are still opaque to me. Robby On Thu, Jun 23, 2011 at 3:16 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: Currently, the documentation completeness checker (a wonderful tool; thanks, Robby!) for Typed Racket complains that `-' and `with-handlers' are not documented when provided from `typed/scheme', `typed/scheme/base', and `typed-scheme'. However, these identifiers are fine when provided from `typed/racket', and are both defined in modules where `check-docs' finds the documentation for other things just fine, such as `define:' and `All'. The documentation looks like this: (declare-exporting typed/scheme/base typed/scheme typed-scheme #:use-sources (typed-scheme/typed-scheme typed-scheme/base-env/prims typed-scheme/base-env/extra-procs typed-scheme/base-env/base-types typed-scheme/base-env/base-types-extra)) where `-' is defined in `typed-scheme/base-env/base-types-extra' and `with-handlers' is defined in `typed-scheme/base-env/prims'. Is there something else I should be doing here? Is there a bug in `check-docs'? -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
Is the with-handlers that typed/racket exports the same identifier as the one exported by racket, or is it a different binding? Robby On Fri, Jun 24, 2011 at 2:46 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: On Wed, Jun 22, 2011 at 6:53 PM, Robby Findler ro...@eecs.northwestern.edu wrote: To really know what is going on, one has to trace thru the re-provides for each of these identifiers and match them up to the declare-exporting declarations. In the declaration below, you're essentially saying any identifiers documented in this module should appear to come from the typed/scheme/base, typed/scheme, and typed-scheme modules, but they are really actually exported from one of the modules listed in the #:use-sources keyword which means, to the documentation system that any module that re-exports an identifier from, say, typed-scheme/base-env/base-types-extra, will have its documentation attached to the docs in the file with the declare-exporting below and the docs system will then point userse to typed/scheme/base. I don't think that this is what you want, since you probably want to to point people to typed/racket. That's not what's going on here, although you couldn't tell that from my email. That `declare-exporting' is in a subsection which only documents `typed/scheme' etc, and not any of the actual forms in Typed Racket. To know what the right answer is for the declare-exporting below, I'd have to know how typed/racket fits into the picture. In particular, is it re-exporting things from typed/scheme? Or from those helper modules you have listed? Or from some other place? It's probably easier to just consider `typed/racket/base' and `typed/scheme/base' here. Both of them export identifiers from the modules listed in the `declare-exporting' declaration. For example, `with-handlers' is defined in `typed-scheme/base-env/prims'. Here's what the documentation for `typed/racket/base' looks like: @(defmodulelang* (typed/racket/base typed/racket) #:use-sources (typed-scheme/typed-scheme typed-scheme/base-env/prims typed-scheme/base-env/extra-procs typed-scheme/base-env/base-types typed-scheme/base-env/base-types-extra)) Also, I don't think this is a problem with the general setup of documentation for Typed Racket. In particular, the identifier `define-type' is defined in the same module as `with-handlers', and it gets handled properly by Scribble, by DrRacket, and by `check-docs'. You can see this by searching for `define-type' in the documentation, or for `U', which is defined in the same module as `-'. Instead, I think the problem is that `with-handlers' and `-' are both identifiers exported from `racket', and this is causing some sort of confusion in the Scribble doc system, but I don't know exactly what, and I'm therefore confused about how to try to fix it. Of course, it might be something totally different, also -- the vagaries of Scribble linking are still opaque to me. Robby On Thu, Jun 23, 2011 at 3:16 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: Currently, the documentation completeness checker (a wonderful tool; thanks, Robby!) for Typed Racket complains that `-' and `with-handlers' are not documented when provided from `typed/scheme', `typed/scheme/base', and `typed-scheme'. However, these identifiers are fine when provided from `typed/racket', and are both defined in modules where `check-docs' finds the documentation for other things just fine, such as `define:' and `All'. The documentation looks like this: (declare-exporting typed/scheme/base typed/scheme typed-scheme #:use-sources (typed-scheme/typed-scheme typed-scheme/base-env/prims typed-scheme/base-env/extra-procs typed-scheme/base-env/base-types typed-scheme/base-env/base-types-extra)) where `-' is defined in `typed-scheme/base-env/base-types-extra' and `with-handlers' is defined in `typed-scheme/base-env/prims'. Is there something else I should be doing here? Is there a bug in `check-docs'? -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
On Jun 23, 2011 6:17 PM, Robby Findler ro...@eecs.northwestern.edu wrote: Is the with-handlers that typed/racket exports the same identifier as the one exported by racket, or is it a different binding? 'with-handlers' in 'typed/racket' is a different binding. Basically, it just adds some annotations to help the type checker. Robby On Fri, Jun 24, 2011 at 2:46 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: On Wed, Jun 22, 2011 at 6:53 PM, Robby Findler ro...@eecs.northwestern.edu wrote: To really know what is going on, one has to trace thru the re-provides for each of these identifiers and match them up to the declare-exporting declarations. In the declaration below, you're essentially saying any identifiers documented in this module should appear to come from the typed/scheme/base, typed/scheme, and typed-scheme modules, but they are really actually exported from one of the modules listed in the #:use-sources keyword which means, to the documentation system that any module that re-exports an identifier from, say, typed-scheme/base-env/base-types-extra, will have its documentation attached to the docs in the file with the declare-exporting below and the docs system will then point userse to typed/scheme/base. I don't think that this is what you want, since you probably want to to point people to typed/racket. That's not what's going on here, although you couldn't tell that from my email. That `declare-exporting' is in a subsection which only documents `typed/scheme' etc, and not any of the actual forms in Typed Racket. To know what the right answer is for the declare-exporting below, I'd have to know how typed/racket fits into the picture. In particular, is it re-exporting things from typed/scheme? Or from those helper modules you have listed? Or from some other place? It's probably easier to just consider `typed/racket/base' and `typed/scheme/base' here. Both of them export identifiers from the modules listed in the `declare-exporting' declaration. For example, `with-handlers' is defined in `typed-scheme/base-env/prims'. Here's what the documentation for `typed/racket/base' looks like: @(defmodulelang* (typed/racket/base typed/racket) #:use-sources (typed-scheme/typed-scheme typed-scheme/base-env/prims typed-scheme/base-env/extra-procs typed-scheme/base-env/base-types typed-scheme/base-env/base-types-extra)) Also, I don't think this is a problem with the general setup of documentation for Typed Racket. In particular, the identifier `define-type' is defined in the same module as `with-handlers', and it gets handled properly by Scribble, by DrRacket, and by `check-docs'. You can see this by searching for `define-type' in the documentation, or for `U', which is defined in the same module as `-'. Instead, I think the problem is that `with-handlers' and `-' are both identifiers exported from `racket', and this is causing some sort of confusion in the Scribble doc system, but I don't know exactly what, and I'm therefore confused about how to try to fix it. Of course, it might be something totally different, also -- the vagaries of Scribble linking are still opaque to me. Robby On Thu, Jun 23, 2011 at 3:16 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: Currently, the documentation completeness checker (a wonderful tool; thanks, Robby!) for Typed Racket complains that `-' and `with-handlers' are not documented when provided from `typed/scheme', `typed/scheme/base', and `typed-scheme'. However, these identifiers are fine when provided from `typed/racket', and are both defined in modules where `check-docs' finds the documentation for other things just fine, such as `define:' and `All'. The documentation looks like this: (declare-exporting typed/scheme/base typed/scheme typed-scheme #:use-sources (typed-scheme/typed-scheme typed-scheme/base-env/prims typed-scheme/base-env/extra-procs typed-scheme/base-env/base-types typed-scheme/base-env/base-types-extra)) where `-' is defined in `typed-scheme/base-env/base-types-extra' and `with-handlers' is defined in `typed-scheme/base-env/prims'. Is there something else I should be doing here? Is there a bug in `check-docs'? -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
On Jun 23, 2011 6:39 PM, Robby Findler ro...@eecs.northwestern.edu wrote: I think I'd need to actually look at the code next. I didn't seem to find it, tho; can you give me a pointer? It should be in 'collects/typed-scheme/scribblings/ts-reference.scrbl' for typed/racket and 'collects/typed-scheme/scribblings/reference/compatibility.scrbl' for typed/scheme. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
On Fri, Jun 24, 2011 at 8:58 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote:
On Jun 23, 2011 6:39 PM, Robby Findler ro...@eecs.northwestern.edu
wrote:
I think I'd need to actually look at the code next. I didn't seem to
find it, tho; can you give me a pointer?
It should be in 'collects/typed-scheme/scribblings/ts-reference.scrbl' for
typed/racket and
'collects/typed-scheme/scribblings/reference/compatibility.scrbl' for
typed/scheme.
I don't see any docs for with-handlers in there:
[robby@gaoping] ~/git/exp/plt/collects/typed-scheme/scribblings$ find
. -name \*scrbl -exec grep -H with-handlers {} \;
[robby@gaoping] ~/git/exp/plt/collects/typed-scheme/scribblings$
Perhaps the confusion is this?: scribble only associates documentation
with actual bindings (well, when you have re-exporting and use
#:with-sources the situation is more complex, but what I'm writing in
this sentence is the right way to think of it as a baseline and then
other things are exceptions) so because the typed/racket with-handlers
binding is a different binding, it needs different @defwhatever.
And, as further rationale for that (something that has been said
before, but I forget if it was said here or not), macros can tell the
difference so documenting the bindings separately, even if all the
docs say is behaves like X [with link], is the right thing.
Or are there actually docs that I still just didn't find?
Robby
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
On Thu, Jun 23, 2011 at 9:19 PM, Robby Findler
ro...@eecs.northwestern.edu wrote:
On Fri, Jun 24, 2011 at 8:58 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu
wrote:
On Jun 23, 2011 6:39 PM, Robby Findler ro...@eecs.northwestern.edu
wrote:
I think I'd need to actually look at the code next. I didn't seem to
find it, tho; can you give me a pointer?
It should be in 'collects/typed-scheme/scribblings/ts-reference.scrbl' for
typed/racket and
'collects/typed-scheme/scribblings/reference/compatibility.scrbl' for
typed/scheme.
I don't see any docs for with-handlers in there:
[robby@gaoping] ~/git/exp/plt/collects/typed-scheme/scribblings$ find
. -name \*scrbl -exec grep -H with-handlers {} \;
[robby@gaoping] ~/git/exp/plt/collects/typed-scheme/scribblings$
Perhaps the confusion is this?: scribble only associates documentation
with actual bindings (well, when you have re-exporting and use
#:with-sources the situation is more complex, but what I'm writing in
this sentence is the right way to think of it as a baseline and then
other things are exceptions) so because the typed/racket with-handlers
binding is a different binding, it needs different @defwhatever.
And, as further rationale for that (something that has been said
before, but I forget if it was said here or not), macros can tell the
difference so documenting the bindings separately, even if all the
docs say is behaves like X [with link], is the right thing.
Or are there actually docs that I still just didn't find?
I think your copy of the tree must be out of date; you can see the
docs for `with-handlers' in git head here:
https://github.com/plt/racket/blob/master/collects/typed-scheme/scribblings/reference/special-forms.scrbl#L387
--
sam th
sa...@ccs.neu.edu
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
On Fri, Jun 24, 2011 at 9:27 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote:
On Thu, Jun 23, 2011 at 9:19 PM, Robby Findler
ro...@eecs.northwestern.edu wrote:
On Fri, Jun 24, 2011 at 8:58 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu
wrote:
On Jun 23, 2011 6:39 PM, Robby Findler ro...@eecs.northwestern.edu
wrote:
I think I'd need to actually look at the code next. I didn't seem to
find it, tho; can you give me a pointer?
It should be in 'collects/typed-scheme/scribblings/ts-reference.scrbl' for
typed/racket and
'collects/typed-scheme/scribblings/reference/compatibility.scrbl' for
typed/scheme.
I don't see any docs for with-handlers in there:
[robby@gaoping] ~/git/exp/plt/collects/typed-scheme/scribblings$ find
. -name \*scrbl -exec grep -H with-handlers {} \;
[robby@gaoping] ~/git/exp/plt/collects/typed-scheme/scribblings$
Perhaps the confusion is this?: scribble only associates documentation
with actual bindings (well, when you have re-exporting and use
#:with-sources the situation is more complex, but what I'm writing in
this sentence is the right way to think of it as a baseline and then
other things are exceptions) so because the typed/racket with-handlers
binding is a different binding, it needs different @defwhatever.
And, as further rationale for that (something that has been said
before, but I forget if it was said here or not), macros can tell the
difference so documenting the bindings separately, even if all the
docs say is behaves like X [with link], is the right thing.
Or are there actually docs that I still just didn't find?
I think your copy of the tree must be out of date; you can see the
docs for `with-handlers' in git head here:
https://github.com/plt/racket/blob/master/collects/typed-scheme/scribblings/reference/special-forms.scrbl#L387
Ah, right. Sorry.
I think the problem is that with-handlers is actually called
with-handlers: in the place where it exported (as far as the
declare-exporting is concerned) so it is not getting connected with
the identifier named with-handlers after the renaming happens.
That is, way to interpret the argument to #:with-sources is I am
documented exports from this module and the earlier arguments to
declare-exporting (typed/scheme/base typed/scheme typed-scheme in this
case) are just used in the documentation to print out what the exports
are; they aren't actually used in a meaningful way internally in
scribble to connect anything to anything else.
So I think the fix is to do the renaming for with-handlers before it
gets exported from typed-scheme/base-env/prims (or introduce another
module and put that one in the #:use-sources and use it as the one
where the re-providing is happening).
I didn't actually try this out (I made a quick attempt, but there are
several changes required to just move the renaming into prims.rkt),
tho, so I may be getting this wrong
Robby
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Strange problem with `check-docs' and `#:use-sources'
To really know what is going on, one has to trace thru the re-provides for each of these identifiers and match them up to the declare-exporting declarations. In the declaration below, you're essentially saying any identifiers documented in this module should appear to come from the typed/scheme/base, typed/scheme, and typed-scheme modules, but they are really actually exported from one of the modules listed in the #:use-sources keyword which means, to the documentation system that any module that re-exports an identifier from, say, typed-scheme/base-env/base-types-extra, will have its documentation attached to the docs in the file with the declare-exporting below and the docs system will then point userse to typed/scheme/base. I don't think that this is what you want, since you probably want to to point people to typed/racket. To know what the right answer is for the declare-exporting below, I'd have to know how typed/racket fits into the picture. In particular, is it re-exporting things from typed/scheme? Or from those helper modules you have listed? Or from some other place? Robby On Thu, Jun 23, 2011 at 3:16 AM, Sam Tobin-Hochstadt sa...@ccs.neu.edu wrote: Currently, the documentation completeness checker (a wonderful tool; thanks, Robby!) for Typed Racket complains that `-' and `with-handlers' are not documented when provided from `typed/scheme', `typed/scheme/base', and `typed-scheme'. However, these identifiers are fine when provided from `typed/racket', and are both defined in modules where `check-docs' finds the documentation for other things just fine, such as `define:' and `All'. The documentation looks like this: (declare-exporting typed/scheme/base typed/scheme typed-scheme #:use-sources (typed-scheme/typed-scheme typed-scheme/base-env/prims typed-scheme/base-env/extra-procs typed-scheme/base-env/base-types typed-scheme/base-env/base-types-extra)) where `-' is defined in `typed-scheme/base-env/base-types-extra' and `with-handlers' is defined in `typed-scheme/base-env/prims'. Is there something else I should be doing here? Is there a bug in `check-docs'? -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
