On 20/02/2013 6:22 AM, Mike Duigou wrote:
Thank you for the feedback David.
So what got updated, if anything, before the push?
The biggest gripe I have with reviewing all this stuff is being able to
keep track of what comments have been made, what comments have been
acted upon and what is still outstanding. I'd love to see a nightly doc
build with change bars; or a doc build with "annotations" highlighting
known issues. Don't know if we have any tools capable of that though.
On Feb 18 2013, at 21:29 , David Holmes wrote:
package-info.java
I've flagged this elsewhere but you may not have seen it:
+ * Predicate<String>
If we use < then we should also use >.
It's not required to use > in HTML 4.01 transitional or HTML 5.0. Doclint was
complaining about this but it has (or soon will be) amended. It could still be a style
requirement to use >
Nothing like being inconsistent :( (that's directed at HTML standard)
I will push this changeset with ">" but assume that if the decision is to require
">" then doclint will remind us thoroughly and repeatedly to correct this before Java 8
is released.
Aside: it would be much easier to maintain consistent style if we used a
"template" to define the main outline of each family of interfaces and
generated the specializations from that (similar to how we generate the various
bytebuffer classes).
Like Chris I have mixed feelings about templating for similar reasons. Our
current generated sources work very poorly with IDEs. If we can improve the
user experience with generated sources I would be very much willing to consider
it.
As I replied to Chris I didn't mean that as a permanent feature or even
something committed at this stage - simply a tool to help with these
repetitive definitions of class/method docs to ensure that they are
consistent in the way they name and express things. Maybe there isn't
enough commonality to make this worthwhile (you may still have multiple
templates to keep consistent), but I know from past experience that this
level of consistency is one of the hardest things to get right - it is
tedious and error prone.
Cheers,
David
Thanks again!
Mike
