morethoughts.java

// The extra .stream() feels logically equivalent to..

        // Convert annotations on each method's params
        clazz.getMethods().stream()
                .flatMap(method -> method.getParameters().stream())  // <---
                .flatMap(parameter -> parameter.getAnnotations().stream()) // <---
                .forEach(converter);

// needing to call .iterator() in a loop

        final List<Param> params = getParams(s);
        for (final Param param : params.iterator()) {  // <---
            map.put(param.used, param.suggested);
        }

// It's not that it's THAT bad, but that it is always needed.  We added an 
// Interable interface and tied it into the language itself so this is possible.

        final List<Param> params = getParams(s);
        for (final Param param : params) {
            map.put(param.used, param.suggested);
        }

// Maybe we could add a Streamable interface so this is possible

        clazz.getMethods().stream()
                .stream(Method::getParameters)
                .stream(Parameter::getAnnotations)
                .forEach(converter);

// Adding the Iterable interface and tying the language to it feels braver than 
// adding a Streamable interface to the Stream class, however both feel on the
// same level of impact.  With Iterable and loops someone going out of fashion
// maybe we want to carry the consistency forward to its replacement?