Community
Participate
Working Groups
When creating a DOM/AST tree, the javadoc of body declarations are not set if the compiler options passed to the ASTParser don't enable the compiler option JavaCore.COMPILER_DOC_COMMENT_SUPPORT. I could not find in the spec of the body declaration node a mention that this option need to be set. I think the javadoc node should be set regardless of the compiler option. I don't expect errors to be reported on the javadoc links, but I expect the Javadoc node to be available if any.
Do you mean that we have to force this option while building the DOM/AST nodes, even if the user hasn't set it on the compiler or should we change the spec to warn the user?
It should be clear when the javadoc nodes can be retrieved out of a DOM/AST tree. I think we should have two options: 1) to set the javadoc node 2) to resolve the javadoc node 2) implies 1), but 1) doesn't need 2). This would also be useful for 1.6 purpose.
We encountered this problem working on a javadoc tag updater for API tooling. We have a visitor which adds missing javadoc tags for a variety of restrictions and in the case of interfaces, even if there is a javadoc section, we end up creating a new one to add a missing tag. Consider the following example: BEFORE /** * A runnable that represents one logical evaluation * to be run in a target thread. * <p> * Clients are intended to implement this interface. * </p> * * @see org.eclipse.jdt.debug.core.IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int, boolean) * @since 2.0 */ public interface IEvaluationRunnable { ... } AFTER /** * @noimplement This interface is not intended to be implemented by clients. */ /** * A runnable that represents one logical evaluation * to be run in a target thread. * <p> * Clients are intended to implement this interface. * </p> * * @see org.eclipse.jdt.debug.core.IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int, boolean) * @since 2.0 */ public interface IEvaluationRunnable { ... } note: the new tag should appear with the other tags in the javadoc block (and does for other TypeDeclarations)
The only thing you need to do to fix this issue is to set ON the compiler option 'Process Javadoc comments'. Its id is "org.eclipse.jdt.core.compiler.doc.comment.support" and the corresponding boolean field of CompilerOptions is 'docCommentSupport'. Then, the Javadoc node will be created while building the DOM/AST tree and your tag will be added properly in the existing Javadoc node instead of creating a new node... Note that if there are warnings in existing code Javadoc comments, they would be reported only if the binding were resolved. And after having discussed with Olivier, I understood that it should be not the case for your need. ----------------- You can verify this behavior using the JDT/UI's ASTView on the simple following test case: /** * @see Unknown */ public class Test {} By default the ASTView resolve bindings, so you'll see at the bottom of the view: - > compiler problems(1) + Javadoc: Unknown cannot be resolved to a type To have no problem, just open the ASTView contextual menu and uncheck 'Create bindings' item. Then, at the bottom of the view, you can see now: > compiler problems(0)
Do we have a use case for having this option disabled? We could also just deprecate the option, enable it all the time and remove the preference in the UI. Observations in I20080220-1400: - content assist does not read the option (works always) - code select does not read the option (works always) - Javadoc nodes are flat in global comments list (as specified in JavaCore.COMPILER_DOC_COMMENT_SUPPORT), but getJavadoc() on ASTNodes returns null, not the flat node.
Olivier, what do you want to do about this?
Resolving javadoc has a side-effect on unused imports. This is why this option (-enableJavadoc) is enabled by default in the Eclipse build. What I want is to be able to get the javadoc comment without the need to resolve them. So deprecating the option and enabling it by default could be one way to do it as long as this doesn't have bad side-effect for existing code base.
This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. As such, we're closing this bug. If you have further information on the current state of the bug, please add it and reopen this bug. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant. -- The automated Eclipse Genie.
