Improved documentation of some object model classes

[smarr]

This PR adds some comments to Layout.createShape(..), Location, and Property.

Not sure whether the term 'language-specific' is ideal, but I wanted to document which elements are free for implementers to use.

Ping @jtulach and @woess.

[chumer]

Glossed over it. Looks good.

[chumer]

@woess Can you create something else than a root shape manually? Maybe we should name the method also createRootShape.

[woess]

We currently don't have any explicit concept of a root shape in names. But yes, you can only create root shapes this way. I'll consider renaming it.

[woess]

Looks good.

[jtulach]

Why don't we document method return values in Javadoc? My IDE complains about its being non-present...

[smarr]

It looked redundant to me. Should it be documented?

[jtulach]

Documenting return type of a method is "redundant"? Redundant to what? I am looking for example at createShape method which is missing return tag, and I don't think adding:

@return new instance of shape that can be used to ....

would hurt.

[smarr]

Ok, just for the sake of argument, and since I am not really used to writing JavaDoc, here my reasoning and my questions:

When looking at the createShape(...) methods, I was wondering what those arguments mean.
And, it is quite complex to figure out what they are eventually used for. I had to step through 7-10 or so methods to see the final constructor. And then, I had to see all the uses of these fields, which were not documented either. So, my main objective was to safe other people that kind of work and document those basic parameters.

At no point in the process I had a question about the returned object, because well, createShape(...) kind of says it all. Of course, it does not tell me anything about the invariants that each shape fulfills, which might also differ between the methods (I don't think they do).

So, ok, I thought, I'd add this comment:

/**
 * Create a root shape.
 *
 * @param objectType that describes the object instance with this shape.
 */

Eclipse's template also gave me the @return. But since I just typed Create a root shape., which essentially duplicates the method name, in my eyes it was redundant to what I could write for @return.

Thinking about it now, I guess, I did feel it isn't very DRY, and I didn't want to have three lines that say essentially the same.

So, now the question for me is whether we want the @return for consistency everywhere? And, what one should usually document in the @return. Are there any typical properties/invariants that are commonly put there?

[woess]

I've seen too many @return descriptions that just repeat what the method description already said (usually getters and the like). How that improves javadoc is beyond me.
My rule of thumb is, it should either add additional information about the return value or summarize what the method returns after a long description of what the method does. Otherwise it's redundant.

[jtulach]

In case you want to avoid duplication, I would prefer less verbose prose section and more descriptive @return value - that is the structured information about the method, not the prose section.

One property that should be put into @return section is whether it can return null or not. Different projects have different rules for that - I don't know what Truffle policy is - probably there is none yet.