Preface: There have been a number of times that I've seen something in the documentation that I would like to suggest an improvement to -- the occasional typo, an idea for a clarifying example, etc. Unfortunately, finding specific parts of the documentation in git feels extremely difficult. There are several different racket repositories on Github and the documentation sprawls across many .scrbl fragments instead of being gathered in whole pages that map to the URLs on the website. Perhaps if I spent a few hours poring over it I could figure out the underlying pattern and then everything would be obvious, but I'm afraid I lack the energy. If someone wants to put together an easy-to-follow tutorial on how to submit documentation changes, I'd love to read it.
Until then, submitting pull requests against the documentation is simply too high a bar for me. Still, I would like to be helpful to the community, so I've got one here in text form. I'm not sure if this is welcome or if there's a specific person to submit to or etc -- please let me know and I either won't submit more or won't send them to the list. SUGGESTION: Here is a suggested bit of documentation to be appended to the 'struct-info' section of the docs at https://docs.racket-lang.org/reference/inspectors.html?q=struct-info#%28def._%28%28quote._~23~25kernel%29._struct-info%29%29 ---------START Note that structs are placed under the control of the @italic{parent} of the inspector provided at their definition site, or the parent of the default inspector if one was not provided. As a result, struct-info is unlikely to return useful information unless you or your environment have changed the current-inspector value at some point. See @secref["inspectors" #:doc '(lib "scribblings/reference/reference.scrbl")] for more detail. ----------END And here is a suggested bit of documentation for https://docs.racket-lang.org/reference/inspectors.html. This is a lightly edited version of the explanation that Jack Firth gave me in a separate thread, with an additional bit derived from code that Matthias provided. I recommend replacing the second paragraph with the following: ---------START When a structure type is created, an inspector can be supplied. The given inspector is @bold{not} the one that will control the new structure type; instead, the given inspector’s @bold{parent} will control the type. This prevents modules from reflecting or modifying structs defined by other modules. The reason for this is that a module that defines an opaque struct type (that is, one that is not transparent or prefab) is expected to be responsible for exporting to other modules all the functions that are necessary for using that type. Anything not explicitly exported by the module is not allowed, even through reflective operations like struct-info. The exception to this rule is when some entity above the modules is controlling them all, such as a debugger, an IDE, or a server running client-supplied code. In these cases, the controlling code has the option to make a child inspector and run all the modules under that child inspector, giving the controlling code access to all struct types through the parent inspector. This kind of setup can be nested to arbitrary depth. The effect of the above is that in most cases you will not be able to reflect a structure by way of struct-info etc. Finally, note that the constructor for a type has the same name as the transformer binding for that type. Therefore, there is a pitfall with this code: @racketblock{ (struct person (name age)) (provide person) } It exports both the constructor and the transformer binding, thereby making it possible for another module to reflect your struct and potentially violate its invariants. In order to prevent this, set a contract on the export: @racketblock{ (struct person (name age)) (provide (contract-out (person (-> string natural-number/c person?)))) } ----------END -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
