Community
Participate
Working Groups
We should add the following topic 'Java development user guide > Tasks > Detecting problems in Java code' under which we can talk about Null Annotations, Resource leaks, Incomplete switch (?), anything else which can be non-obvious and where some guidance (e.g. last point from bug 378724 comment 0) and/or examples can aid the user. Some of the content (at least the examples) should already be available in N&N docs and also some of our blog posts. Stephan, you want to take this up?
Thanks for the heads up, I was already wondering, where to put such documentation. A new task heading definitely makes sense. Thinking about null annotations I would probably better like a heading like "Improving Java code quality". I hope I didn't promise more than I'm able to deliver in time, but I'll certainly do my best.
(In reply to comment #1) Thanks Stephan! > I would probably better like a heading like > "Improving Java code quality". That also works for me in place of 'Detecting problems in Java code'.
Stephan, we're closing in on the RC2 build. Will it be possible for you to do the doc today? I'll do a quick review and we can release it in time for the build.
(In reply to comment #3) > Stephan, we're closing in on the RC2 build. Will it be possible for you to do > the doc today? I'll do a quick review and we can release it in time for the > build. Sorry, I wasn't aware of the deadline. Just yesterday I built the RC1 for Object Teams and RC2 is already closing, too?? I also lost half a day to the sudden death of a hard disk ... I can start writing tonight, but I'd really like to spend a bit more time to provide some quality... hm ...
(In reply to comment #4) > (In reply to comment #3) > > Stephan, we're closing in on the RC2 build. Will it be possible for you to do > > the doc today? I'll do a quick review and we can release it in time for the > > build. > > Sorry, I wasn't aware of the deadline. Just yesterday I built the RC1 for > Object Teams and RC2 is already closing, too?? > I also lost half a day to the sudden death of a hard disk ... > > I can start writing tonight, but I'd really like to spend a bit more time to > provide some quality... hm ... Oh in that case lets not rush it. RC3 should be more convenient for this. Lets target early next week.
Created attachment 216332 [details] Draft documentation Here's a draft of (a) a general introduction and (b) an explanation of annotation based null analysis.
Considering the amount of discussion that has flown into these subjects over the last year it seems *a lot* has to be carefully explained. Given the tight schedule (for which I apologize, should've started way earlier), I propose the following: - For now focus on explaining what it *is*, rather than a full blown comprehensive tutorial on how to *use* (although the current draft already contains a few recommendations). - Setup a new wiki page discussing methods how to make best use of these new features (like: migration strategies when adopting null annotations). - Make a link from the help pages to the wiki pages. Hopefully, during the Kepler cycle this wiki page(s) will mature and by then can be merged into the help system. Please comment on the draft. It's already a bit lengthy but I feel that's the minimum level of detail we need to actually explain the feature. I could probably use some more code examples, some pretty printing for the code examples etc. I haven't yet checked HTML validity but hopefully this will be an easy task in the end, given that I'm now using the Web Page editor (rather than a plain text editor as I did before).
(In reply to comment #6) > Created attachment 216332 [details] [diff] > Draft documentation > > Here's a draft of (a) a general introduction and (b) an explanation of > annotation based null analysis. Thanks Stephan! This already looks reasonably good, and I released it with a few minor corrections (spelling errors and incorrect links). We can continue to polish the released version... (In reply to comment #7) > - For now focus on explaining what it *is*, rather than a full blown > comprehensive tutorial on how to *use* (although the current draft already > contains a few recommendations). Sure. > - Make a link from the help pages to the wiki pages. Not sure if we should link to the wiki pages from help. I am not aware of such a precedent in JDT. > I haven't yet checked HTML validity I will run the chkpii tests and fix any problems that are discovered.
(In reply to comment #0) > Resource leaks, Incomplete switch Stephan, in addition to polishing the page for null-annotations would you also have time to add doc for these two topics?
(In reply to comment #6) > Created attachment 216332 [details] > Draft documentation > > Here's a draft of (a) a general introduction and (b) an explanation of > annotation based null analysis. This doc is good for Juno. We can also add resource leak and swtch-case warning docs (not a comprehensive description though.) I also noticed that the ref-preferences-errors-warnings page was missing the updated doc for switch-case warnings. I added that and released via commit d24dde6b74338cbff7b303640a57a2ea3b1e5a2a
(In reply to comment #8) > (In reply to comment #6) > ... and I released it with a few minor corrections That wasn't actually only helpful. I marked it as a draft because I was going to continue working on it. I packed the local git repo on a stick so I can work on it while travelling. Now we're getting out of sync, mh... (don't tell me merging is *never* a problem with git :) ) Is there an urge to "test" this patch, to have it integrated in the build right now? > > - Make a link from the help pages to the wiki pages. > Not sure if we should link to the wiki pages from help. I am not aware of such > a precedent in JDT. May be the first time, yes. But I have the impression more help than just the explanation we have now, is highly desirable. I would love to have a prominent link to a wiki page, where people get the latest tips and maybe can even contribute their experience. Why not from the help page? I think many other projects are linking from help to their home pages or the like. Any reasons not to do so? As said, I see this as a temporary means until Kepler. (In reply to comment #9) > (In reply to comment #0) > > Resource leaks, Incomplete switch > Stephan, in addition to polishing the page for null-annotations would you also > have time to add doc for these two topics? It's on my schedule for Wednesday.
(In reply to comment #11) > (In reply to comment #8) > > (In reply to comment #6) > > ... and I released it with a few minor corrections > > That wasn't actually only helpful. I marked it as a draft because I was going > to continue working on it. I packed the local git repo on a stick so I can > work on it while travelling. Now we're getting out of sync, mh... > (don't tell me merging is *never* a problem with git :) ) Even my repo blew up yesterday coz i did a pull with the patch still in the workspace. Took away much of my time :(
>> - Make a link from the help pages to the wiki pages. > Not sure if we should link to the wiki pages from help. I am not aware of > such > a precedent in JDT. I'm fine with a link to a wiki page which is in progress, but all current doc should be in Help and not on the wiki itself.
(In reply to comment #11) > (In reply to comment #8) > > (In reply to comment #6) > > ... and I released it with a few minor corrections > > That wasn't actually only helpful. I marked it as a draft because I was going > to continue working on it. I packed the local git repo on a stick so I can > work on it while travelling. Now we're getting out of sync, mh... > (don't tell me merging is *never* a problem with git :) ) > > Is there an urge to "test" this patch, to have it integrated in the build > right now? I thought it would easier for everyone involved to review and tweak it this way, plus having the doc in git makes it easier for me to test and fix chkpii problems. In any case, sorry for the inconvenience caused.
In commit 4dead014822ddfe231cc18386eb72149798f5717 I have pushed: - polish regarding null annotations - new page regarding resource leaks. (HTML has been validated). The null annotations page now has a link to http://wiki.eclipse.org/JDT_Core/Null_Analysis/Adopting_Null_Annotations where I've setup a stub for more hints. I will also link this page from other locations, like e.g., the JDT FAQ. (In reply to comment #13) > I'm fine with a link to a wiki page which is in progress, but all current doc > should be in Help and not on the wiki itself. Yes, whatever we manage to do now goes into Help. Still pending: completeness of switch statements. Scheduled for tomorrow.
In commit 1c108536e21f29fd94088b9dce2137a35cd8a3b4 I have pushed: - new page regarding switch statements - update batch compiler help regarding switch (and fixed table layout) from my p.o.v. this concludes the scheduled work in this bug, leaving the bug open for now to await review comments.
Ayush may be offline a good part of next few days, Jay, could you review the changes ? I also plan to do so.
Created attachment 216771 [details] Minor corrections The documentations changes look good to me. Just a couple of very small corrections you might want to include.
+1 from me
(In reply to comment #18) > Created attachment 216771 [details] > Minor corrections > > The documentations changes look good to me. Just a couple of very small > corrections you might want to include. Released via commit 25885c43cf32bb2ba1b0c57a447e97e7583d8a2f Closing.
