feature: add CtElement#descendantIterator and CtElement#asIterable

[AndreFCruz]

This is a method for obtaining an Iterator over the CtElement's descendants, as suggested in #1077 .
It aims to make the CtIterator class easier to find.

[monperrus]

Thanks a lot for this pull-request.

Could you add a test to verify that one can use this feature in a foreach loop?

[AndreFCruz]

I added a static method CtElement.asIterable that I think facilitates the use of the Iterator.

In this way, a user can iterate with the regular for loop:

for (CtElement elem : CtElement.asIterable(ctElem)) {
        ...
}

and using the iterator's forEachRemaining (as was possible with the previous method)

ctElem.descendantIterator().forEachRemaining((CtElement elem) -> ... );

And added a test for both methods.

[monperrus]

Thanks a lot!

In Spoon, we don't use static interface methods.

Instead of a static method, is it possible to directly have Iterable<CtElement> asIterable() as normal interface method + implementation in CtElementImpl?

Side-note: would you put your test directly in CtIteratorTest.java?

Cheers --Martin

[AndreFCruz]

Sure, moved the method to the class implementation as non-static, and moved all iteration tests to CtIteratorTest.java

[spoon-bot]

API changes: 4 (Detected by Revapi)

Old API: fr.inria.gforge.spoon:spoon-core:jar:6.3.0-20180503.225317-66 / New API: fr.inria.gforge.spoon:spoon-core:jar:6.3.0-SNAPSHOT

	Class no longer implements interface 'java.util.Iterator'.
Old	class CtIterator
New	class CtIterator
Breaking	binary: breaking,
	Class now implements interface 'java.util.Iterator<spoon.reflect.declaration.CtElement>'.
:---:	:---:
Old	class CtIterator
New	class CtIterator
Breaking	binary: non_breaking,
	Super type's type parameters changed from 'java.util.Iterator' to 'java.util.Iterator<spoon.reflect.declaration.CtElement>'.
:---:	:---:
Old	class CtIterator
New	class CtIterator
Breaking	binary: potentially_breaking,

	Method was added to an interface.
Old	none
New	method CtElement#asIterable()
Breaking	binary: non_breaking,

	Method was added to an interface.
Old	none
New	method CtElement#descendantIterator()
Breaking	binary: non_breaking,

	The return type changed covarianly from 'java.lang.Object' to 'spoon.reflect.declaration.CtElement'.
Old	method CtIterator#next()
New	method CtIterator#next()
Breaking	binary: breaking,

[monperrus]

Thanks a lot. I'm OK to merge if nobody disagrees with those two new methods in CtElement.

[pvojtechovsky]

I like this PR too 👍

[monperrus]

Thanks a lot André for your contribution.