Fix eclipse warnings and add java documentation, part 3 (#1670)

[speckyspooky]

Fix eclipse warnings and add java documentation, part 3 (#1670)
and warnings of JavaScript ECMAScript 6 (#1574)

[speckyspooky]

@wimjongman

Hello Wim,
this PR includes changed to solve warnings and add missing documentation.

To solve warnings I changed 2 interfaces and 1 abstract class.
The method-signature is changed on the Return-Value. The return-value is changed from Collection to Collection<IContent>

With this change we are more safty at side of data type casting
but I also know that the interface-method-signature is changed.

What is your opinion on it? I would keep it changed but I will wait for your recommedation of the change.

Details of the interface changes:

class/interface: public interface IElement

=> changed:

Method
- from:		Collection getChildren();
- to:		Collection<IContent> getChildren();

class/interface: public class AbstractElement implements IElement

=> changed:

Property
- from:		transient protected Collection<?> children;
- to:		transient protected Collection<IContent> children;

Method
- from:		public Collection getChildren() {
- to:		public Collection<IContent> getChildren() {

class/interface: public interface IPageContent extends IContainerContent

=> changed:

Method
- from:		Collection getHeader();
- to:		Collection<IContent> getHeader();

Method
- from:		Collection getFooter();
- to:		Collection<IContent> getFooter();

[wimjongman]

Yes, if this is a breaking interface change then we can probably not do that without a proper process.

https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs-2.md

[speckyspooky]

I have not changed parameter-signatures of methods and I have also not added or removed parameters.

I have changed the return-value from raw type "Collection" to "Collection".
So I have changed the raw type to more precision, can this break compatibility?

It is little bit a kind of mixture like your linked documentation and the marked line at my screen.

I figured out this sequence of the description which shows me like my change of a raw-type
and based on this section we should get no problem with it:

[merks]

Parameterizing a raw type is not binary in compatible so this looks fine.

It's a little odd that the only implementation of this method is deprecated:

There's not even an explanation why, and what good does the deprecation do if its' not deprecated in the interface?

[wimjongman]

🙏🙏