Graydon, >> As a solution: I think we need an intermediate step. Not a spec, but >> some detailed design notes. Lar's document was a good >> overview, but drill down on exactly how the mechanisms are meant to >> work would be very helpful to broaden the base of >> implementations. Some examples of the things I'd like to see are: >> >> * Exactly how the scope rules work for various constructs >> * Order of initialization >> * More detail on namespace lookup rules >> * More detail on unqualified variable lookup >> * Type matching rules and conversions >> * More detail on nullability > > I see. I would have hoped these would be visible more or less directly > by inspection: > > * the scope rules and initialization order of each construct are > elaborated production-by-production in eval.sml > > * the namespace lookup scheme is elaborated in multiname.sml, > fixture.sml and defn.sml > > * the unqualified lookup rule starts in eval.sml > (evalLexicalRef -> evalRefExpr -> resolveOnScopeChain -> > Multiname.resolve) > > * the type matching and conversion rules begin with runtime judgments > in eval.sml (evalBinaryTypeOp) and then transition to type.sml > for their type-term-specific parts (groundMatchesGeneric and > findSpecialConversion) > > * the nullability system is more spread out, covering some part > of the type normalizer in type.sml and some part of the property > allocation scheme in eval.sml Thanks. Navigating the RI does take time and I'm pretty poor on ML. The above was not necessarily meant to be definitive, but rather an example of the kinds of things that crop up. Thanks for the tips anyway. > > I'm sad to hear that the RI was not sufficiently clear on these > points, but I guess this was a risk in the choice of language; SML is > terse but also not always familiar. > > Some of the SML code can be "lowered", via a prototype converter I > have written, to english. Notational details are erased but the names > and structure is preserved. Would this be useful? Another possibility > is to expand the internal commentary of the RI, or write some sort of > study guide. Inline comments may be better or easier. Separate documents are hard to maintain. Comments that say: "Here is where XYZ happens" would be helpful. As well as some overview comments that explain where various parts are implemented.
What I find with the RI is that I can understand once piece, but I don't know if that is the sole place that implements or manages an issue. Take scope rules: an implementation can implement these in a variety of ways and places. So you don't know by looking at one piece of code if you have it all. Where the RI is great is to run test cases and see what it actually does. We do this with ASC and the RI quite a bit. > > I'm hesitant to commit to "yet another bit of plain english docs", > both because everyone who could write them already has lots to do, and > because there is nothing guaranteeing that such docs remain current or > honest. As we've seen, it's easy for an english doc -- such as a wiki > page -- to drift into obsolescence if there's not constant energy > spent updating it. Understand, but I've got no easy solution. My recommendation would be: - Add comments and overview inside the RI code itself. - Create an addendum to Lar's document that drills down on key topics to provide more exact operational semantics and details. > > -Graydon > _______________________________________________ Es4-discuss mailing list Es4-discuss@mozilla.org https://mail.mozilla.org/listinfo/es4-discuss
