Review Request : 7029997 : Restyling of SortedMap Javadoc
Hello all; I have made a couple of styling improvements to the JavaDoc for SortedMap; principally conversion of an inline list to use the HTML <ol> tag. The remainder of the changes are updates to the standard javadoc tags. http://cr.openjdk.java.net/~mduigou/7029997/0/webrev/ Thanks, Mike
Looks good; approved, -Joe On 3/22/2011 1:12 PM, Mike Duigou wrote:
Hello all;
I have made a couple of styling improvements to the JavaDoc for SortedMap; principally conversion of an inline list to use the HTML<ol> tag. The remainder of the changes are updates to the standard javadoc tags.
http://cr.openjdk.java.net/~mduigou/7029997/0/webrev/
Thanks,
Mike
The changes look good. I have two minor comment: 1) "ranges.Such" typo, missing space after dot 2) "Though nothing enforces this recommendation as interfaces cannot declare constructors". I'd tend to move this statement to before the list, and maybe put it in parantheses after constructors. Also my personal preference is to stay with "there is no way to" rather than "nothing". That would look like: <p>All general-purpose sorted map implementation classes should provide four "standard" constructors (though there is no way to enforce this ...): This is just my personal preference. I'm ok with your changes as is. -Chris. On 03/22/11 08:12 PM, Mike Duigou wrote:
Hello all;
I have made a couple of styling improvements to the JavaDoc for SortedMap; principally conversion of an inline list to use the HTML<ol> tag. The remainder of the changes are updates to the standard javadoc tags.
http://cr.openjdk.java.net/~mduigou/7029997/0/webrev/
Thanks,
Mike
Thanks for the feedback. On Mar 22 2011, at 16:12 , Chris Hegarty wrote:
The changes look good.
I have two minor comment:
1) "ranges.Such" typo, missing space after dot
corrected.
2) "Though nothing enforces this recommendation as interfaces cannot declare constructors". I'd tend to move this statement to before the list, and maybe put it in parantheses after constructors. Also my personal preference is to stay with "there is no way to" rather than "nothing". That would look like:
<p>All general-purpose sorted map implementation classes should provide four "standard" constructors (though there is no way to enforce this ...):
This is just my personal preference. I'm ok with your changes as is.
How about this version : * <p>All general-purpose sorted map implementation classes should provide four * "standard" constructors. It is not possible to enforce this recommendation * though as required constructors cannot be specified by interfaces. The * expected "standard" constructors for all sorted map implementations are: * <ol>
-Chris.
On 03/22/11 08:12 PM, Mike Duigou wrote:
Hello all;
I have made a couple of styling improvements to the JavaDoc for SortedMap; principally conversion of an inline list to use the HTML<ol> tag. The remainder of the changes are updates to the standard javadoc tags.
http://cr.openjdk.java.net/~mduigou/7029997/0/webrev/
Thanks,
Mike
On 3/22/2011 4:33 PM, Mike Duigou wrote: [snip]
2) "Though nothing enforces this recommendation as interfaces cannot declare constructors". I'd tend to move this statement to before the list, and maybe put it in parantheses after constructors. Also my personal preference is to stay with "there is no way to" rather than "nothing". That would look like:
<p>All general-purpose sorted map implementation classes should provide four "standard" constructors (though there is no way to enforce this ...):
This is just my personal preference. I'm ok with your changes as is. How about this version :
*<p>All general-purpose sorted map implementation classes should provide four * "standard" constructors. It is not possible to enforce this recommendation * though as required constructors cannot be specified by interfaces. The * expected "standard" constructors for all sorted map implementations are: *<ol>
FWIW, while the requirement for a particular suite of constructors isn't enforceable via the type system, it is the sort of extra-linguistic check that could be written as a annotation processor and provided during a compile to enforce the constraint. -Joe
On 03/22/11 11:33 PM, Mike Duigou wrote:
...... How about this version :
*<p>All general-purpose sorted map implementation classes should provide four * "standard" constructors. It is not possible to enforce this recommendation * though as required constructors cannot be specified by interfaces. The * expected "standard" constructors for all sorted map implementations are: *<ol>
This updated version looks much better to me. Thanks, -Chris.
-Chris.
On 03/22/11 08:12 PM, Mike Duigou wrote:
Hello all;
I have made a couple of styling improvements to the JavaDoc for SortedMap; principally conversion of an inline list to use the HTML<ol> tag. The remainder of the changes are updates to the standard javadoc tags.
http://cr.openjdk.java.net/~mduigou/7029997/0/webrev/
Thanks,
Mike
participants (3)
-
Chris Hegarty
-
Joe Darcy
-
Mike Duigou