[racket] Scribble Warning / "on this page"

At Sun, 13 May 2012 21:48:13 +0200, Quentin Rinaldi wrote:
> Thank you !! Yes, now it's better... but i'm not sure to understand the
> "library" concept...
> 
> On my project, I have 3 files :
> 
> projet_class.rkt : all class are defined here (porte% etc...)
> it starts with (provide (all-defined-out))
> 
> projet_definitions.rkt : most of all definitions I use in
> projet_interface.rkt are defined here
> it also starts with (provide (all-defined-out))
> 
> projet_interface.rkt :all the interface, buttons, canvas etc...  the main
> file
> it starts with (require "projet_definitions.rkt" "project_class.rkt")
> 
> But... where is my "library" ? Because if I write (defmod
> "projet_class.rkt"), it works (porte% is recognized in my doc), but it
> doesn't work for my definitions (defproc ...)  (which are originally
> defined in project_definitions.rkt).
> So, where do I have to mention "project_definitions.rkt" ?

A "library" is just a module. The idea is that you're documenting all
the bindings that come from a particular module. If you have bindings
from two different modules, then you should have two sections in the
document, each with its own `defmodule'.

The module name "project_interface.rkt", though, suggests that it
re-exports bindings frmo "project_class.rkt" and
"project_definitions.rkt" that are supposed to be externally visible.
If so, then you probably want just one
`@defmodule["project_interface.rkt"]'.


That said, module names in documentation are usually not written
as strings but as collection-based paths:

 http://docs.racket-lang.org/guide/module-basics.html#(part._link-collection)


> And just one more question :
> 
> If I write this : @racket[porte%] it works (I have a link with the
> definition of the class porte%)
> But if I write the same but with a method of porte% "get-val-out" :
> @racket[get-val-out] it doesn't work (it's not a link) whereas get-val-out
> is recognized as a method of porte% (I mean, in his definition it's a real
> link, in blue).  Can I fix that ?

If you have

 (define porte%
   (class object%
     (define/public (get-val-out) ....)
     ....))

then `porte%' is bound, but `get-val-out' is not bound outside of the
`porte%' class. The `racket' form detects bindings and installs
hyperlinks, but it can't install a hyperlink for `@racket[get-val-out]'
because there's no binding.

Use the `method' form, instead: `@method[porte% get-val-out]'. The
`method' form uses the bindings of the first identifier to local
`defclass'-generated documentation for the second identifier.