Type Hierarchies and Guards in Truffle Languages

[Stefan Marr]

Hi:

> On 08 Jan 2016, at 13:42, christian.humer at gmail.com wrote:
> 
> Hi,
> 
>> Hello Stefan.
>> 
>>> Hope such posts help.
>> 
>> Your post could be even more useful, if included in the Javadoc.

I was thinking about converting it into a blog post as a first step.

>> Do you also
>> think <h3>Choosing Your Guards Wisely</h3> at http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/com/oracle/truffle/api/dsl/Specialization.html#guards--
>> would be better place for a bit reworded version of this text? If so, feel
>> free to turn it into patch.
> I don't think Specialization#guards is the right place. I think Specialization#guards should focus on semantics and minimal examples instead of big examples and their performance implications like this.

I agree, but perhaps a brief note on the performance implications might still be good for `guards` as well?

> I think it would be a better fit in com.oracle.truffle.api.dsl.test.examples.

Not sure I would look there for it either.
I guess, my post is more like a high-level concept documentation, which I at least, would be looking for in some over-arching documentation.
Perhaps, truffle/overview.html [1] would be a better place for a top-down view of things, which the `Specialization#guards` doc could then link?

My reasoning is, that I am not used to find high-level concept discussion at the detailed API documentation. What I am looking for there is short and precise information about how to use something. The same more or less holds for examples. I am not reading examples to get the bigger picture. I am looking for examples when I got a specific problem to solve and am looking for solutions to it. Don’t think I ever looked at the examples package thought.

So, but to fit it into the overview, we would probably want a little more of a high-level intro there directly beside the existing links?

Best regards
Stefan

[1] http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/overview-summary.html#overview.description