Community
Participate
Working Groups
Created attachment 169940 [details] Patch HEAD The Javadoc for a few APIs introduced in 3.6 have some warnings and spelling problems. Attaching the patch.
- Some changes were in 'org.eclipse.jface' (we only own jface.text). They looked good though hence, committed to HEAD. There are some minor issues with the remaining changes: - NewTypeWizardPage.constructCUContent(ICompilationUnit, String, String) ==> the comment is not accurate (there are two reasons for the exception) - java -> Java - no empty lines between tags Please fix that and commit to HEAD.
(In reply to comment #1) > There are some minor issues with the remaining changes: > - NewTypeWizardPage.constructCUContent(ICompilationUnit, String, String) > ==> the comment is not accurate (there are two reasons for the exception) > - java -> Java > - no empty lines between tags > > Please fix that and commit to HEAD. Fixed and Released to HEAD.
I wonder what is the use of a javadoc such as - "@param selection the java text selection" - get rid of the description expected warning? :) The parameter is declared as 'selectionChanged(JavaTextSelection selection)' and looking at the declaration I can see it is a java text selection, the javadoc does not provide any extra information. It is not only this patch here, this is something that generally bothers me. If getting rid of the warning is the only reason I would probably disable/suppress the warning instead of adding meaningless javadoc. Or are there some good reasons for this kind of javadoc that I am missing?
Very often it does add additional value but I agree sometimes it does not. Since there's no special flag/tag for parameters that don't need additional comment, we simply add it everywhere. Note that you can't just ignore the warning for one specific parameter.
Verified that we no longer have Javadoc warnings in any of our APIs.
(In reply to comment #4) > Very often it does add additional value but I agree sometimes it does not. > Since there's no special flag/tag for parameters that don't need additional > comment, we simply add it everywhere. Note that you can't just ignore the > warning for one specific parameter. I would probably leave the warning as it is (or figure out some other way to get rid of it). But I do not feel too strongly either way.
>I would probably leave the warning as This is not an option ;-)
