Community
Participate
Working Groups
All user-visible features around bug 331651 need to be explained in the user documentation. In particular the implementation in bug 440815 defines a new help context (see IJavaHelpContextIds.EXTERNAL_ANNOTATIONS_ATTACHMENT_DIALOG) which needs to be linked to a corresponding help page in o.e.j.doc.user under the heading Reference > Property Pages Conceptual documentation will go the same plugin but heading Tasks > Improving Java code quality.
A first write-up has been pushed via http://git.eclipse.org/c/platform/eclipse.platform.common.git/commit/?id=93ef4f2391c102602862a1b976a7969f33315fa3 Still missing: additions on existing pages: - Installed JREs - Java Build Path Page - batch compiler option
to be continued / finalized in this current RC4 cycle.
Feedback: Overall very good. The documentation answered all my questions that I had while reading it. It's clear. Commas "libraries does not yet consistently specify, where null is allowed, and" Both commas are wrong. "the only option currently is, to specify the external" "external annotations closely mimic, how annotations" Feels wrong here but not 100% sure Wording "you may point into any detail of a type" sounds odd. How about "you may point at any part of a type".
(In reply to Aaron Digulla from comment #3) > Feedback: Thanks! > Commas Am I guilty of killing another patron? (cf. "Eats, Shoots, and Leaves"). :) > Wording > > "you may point into any detail of a type" sounds odd. How about "you may > point at any part of a type". I'm opting for "refer to".
(In reply to Sarika Sinha from bug 331651 comment 84 ) Thanks for reviewing. Your comments relate to task-using_null_annotations.htm, whereas the new page for this bug is task-using_external_null_annotations.htm. Have you seen that one, too? > Document looks great, You may want to go through these sentences once : > 1. If inheritance of null annotations is not enabled one particular > situation is safe from a type theory point of view but may still indicate a > problem. (Something is missing depending on what you intend to say) Let me try by *inserting* some commas for a change: "If inheritance of null annotations is not enabled, one particular situation is safe from a type theory point of view, but may still indicate a problem." Is that clearer? > 2. Therefore, it is again strongly recommended to leave this problems > configured as errors and not to ignore these messages. (this -these ?) You're right. Fixing.
Fixed via http://git.eclipse.org/c/platform/eclipse.platform.common.git/commit/?id=b7897872d3a6f224ee2f3bcf658b8942905c58bb Incorporated review comments, some more polish, and also resolved these items: (In reply to Stephan Herrmann from comment #1) > Still missing: additions on existing pages: > - Installed JREs > - Java Build Path Page Not yet done, will be handled shortly via bug 462147: > - batch compiler option
.
(In reply to Stephan Herrmann from comment #4) > > Wording > > > > "you may point into any detail of a type" sounds odd. How about "you may > > point at any part of a type". > > I'm opting for "refer to". I think "point" here means "with the mouse" so it makes sense. "refer to" would mean "I'm writing a text document which refers to the source code".
(In reply to Aaron Digulla from comment #8) > (In reply to Stephan Herrmann from comment #4) > > > > Wording > > > > > > "you may point into any detail of a type" sounds odd. How about "you may > > > point at any part of a type". > > > > I'm opting for "refer to". > > I think "point" here means "with the mouse" so it makes sense. "refer to" > would mean "I'm writing a text document which refers to the source code". Maybe that's why I originally used "point" (can't remember :) ). If this were under the heading "Creating external annotations" I'd happily change to "point at", but since the enclosing paragraph is more at the conceptual level, not focusing at UI gestures, I'll leave it at the more general "refer to". BTW: more related doc changes can now be found in bug 459180.
(In reply to Stephan Herrmann from comment #5) > (In reply to Sarika Sinha from bug 331651 comment 84 ) > > Thanks for reviewing. Your comments relate to > task-using_null_annotations.htm, whereas the new page for this bug is > task-using_external_null_annotations.htm. Have you seen that one, too? > Looks good apart from typo: Null annotations, or even better, null type anntations (anntations -> annotations)
(In reply to Sarika Sinha from comment #10) > (In reply to Stephan Herrmann from comment #5) > > (In reply to Sarika Sinha from bug 331651 comment 84 ) > > > > Thanks for reviewing. Your comments relate to > > task-using_null_annotations.htm, whereas the new page for this bug is > > task-using_external_null_annotations.htm. Have you seen that one, too? > > > Looks good apart from typo: > Null annotations, or even better, null type anntations (anntations -> > annotations) Eagle eyes! Thanks, fixed.
