Community
Participate
Working Groups
(Although it may be the tip of an iceberg, I am experiencing this particularly with the Members View and Java Text Editor in the Java Browsing perspective.) Comments adjacent to a member declaration (before and after) are sometimes considered as belonging to it and sometimes not. I have studied the affects of Cut and Delete commands in the Members View in the Java Browsing perspective, drag & drop from the Members View to the Type View, and the Show Source of Selected Element Only mode of the Java Text Editor, and they apply complex and differing heuristics. I think it would be reasonable that: (Basic requirement) The member declaration source code is regarded by the Members View as being exactly the source code shown by the Java Text Editor in Show Source of Selected Element Only mode. Editing commands including drag & drop must only affect the source code of the involved members. To fix this, the heuristics for associating comments with member declarations must be unified. As input to this work, I would like to propose a couple of principles to make editing using the Member View commands safer and more profitable: (1) Given one version of the code, the heuristics clearly must associate each comment to either zero or one member declaration. (2) There must be a well defined means of avoiding that a file-related comment (like a header for a sequence of declarations) is associated with any member declaration. This is the reason for the word zero above. The second principle (2) is particularly important to me as it was while trying to figure out the (currently not so well defined) means for keeping heading- like comments out of harms way that I discovered how broken this was. And it does appear that at present there exists no such means. Findings in 3.0 M3: (a) The Cut and Delete commands in the Members View removes all preceding comments not separated from the deleted member declaration with at least on blank line, and all succeeding comments separated from the next member with at least on blank line. Javadoc comments are treated differently. However if the member is a method and the only member of the class, all preceding comments are removed but no succeeding ones. (b) The Show Source of Selected Element Only text editor mode will show all comments preceding the selected member in addition to the member declaration. (c) Drag & drop move of a member into classes and interfaces copies all preceding comments to the receiver but removes some preceding ones and some succeeding ones from the provider. Exactly which comments that are thereby lost or duplicated is dependent on style (/**, /*, //) and the use of blank lines. The behavior gives an impression of a mix of (a) and (b) above. Playing around with code like the following has proven educational: public class Test2 { /////////////////////////////////////////////////// // METHODS /////////////////////////////////////////////////// public void preceding () {} // moveTest before /** * moveTest doc */ public void moveTest () {} // moveTest after /** * succeeding doc */ public void succeeding () {} /////////////////////////////////////////////////// // ----- /////////////////////////////////////////////////// }
I forgot to mention that Bug 41734 addresses a subset of this. I doubt that just fixing 41734 is meningfull---the rest of the adjacent comment handling being the way it is, no one is likely to notice a partial improvement.
We currently have several different heuristics of how comments are assigned to members. Cut-copy paste uses the ASTRewriter heuristic, show selected element and other Java element based ranges a different one. Moving to jdt.core
Frederic: pls double check this scenario is now supported with extended source range approach.
I'd love to. But what exactly is the extended source range approach?
comment 3: Currently this is not the case. M8 jdt-core implementation for comment mapping (class org.eclipse.jdt.core.dom.DefaultCommentMapper) uses exactly the same heuristic than jdt-ui written in org.eclipse.jdt.internal.corext.dom.CommentMapper class. As jdt-ui was our first main client for this, it was the first goal of comment mapping transfer: do the same as before. Note however that these two classes do not work exactly the same due to some unhandled cases discovered on jdt-ui heuristic and fixed during the transfer... We were lacking of input to decide how to change existing heuristic or propose new ones. Here's a input which sounds interesting and I'll see if it would be possible to open our comment mapping class to take it into account.
comment 4: DOM AST nodes have a start position and a length calculated when converting compiler AST nodes. They are based on code but does not include leading and trailing comments (comments are not meaningful for compiler...). Extended range for a DOM AST node is made of an extended start position which includes leading comment and an extended length which includes trailing comments. You can get extended start position and extended length of a DOM AST nodeare using org.eclipse.jdt.core.dom.CompilationUnit following methods: - getExtendedStartPosition(ASTNode) - getExtendedLength(ASTNode) These methods are really useful to know if a comment is attached to a node because it's the extended range which is used to answer it... Note that there's an exception for javadoc comment preceeding body declaration (a method declaration for example). This kind of comments is included in the node itself by compiler due to the fact that it can include @deprecated information...
Because this is starting to get technical to the point of missing it (the pont), I would like to emphasize that to understand what this bug report is about, one has to see the problem from the outside, from the view point of the user of the "Refactor" command, drag&drop of program elements, and the "Show source of selected element only" editor mode: (1) How can this user predict what will happen when a code moving/replacing/coping operation is performed? (2) How can this user control the affects of such operations on comments contained in the affected files? After thinking this over for a while I've come to the following conclusions: (a) What it's about is knowing and being able to control which comments belong, and which comments do not belong, to a given class member. (b) One reliable source of such knowledge should naturally be the "Show source of selected element only" editor mode. It's a bit closer at hand to the average user than astview :-) (thanks for the screen dump though) (c) This could be end of story were it not for the need to support trailing comments and file adornments. By the latter I mean comments not connected to any method and thus invisible to users of the "Show source of selected element only" editor mode. Without these disturbing notions, all comments preceding a member would simply and necessarily belong to it; however with them, comes the necessity of more or less complicated heuristics. (d) Because other peoples obnoxious insistence on using their own source code conventions, allowing for an appropriate identification of trailing comments and file adornments does require a degree of adaptivity. My conclusion is that "User preferences" has to be extended with a section on this. As a side effect, such settings would catch the user's attention and make her conscious of these facilities. Something along these lines: -------------------------------------------------------- Identifying Trailing comments and File Adornments In addition to the closest preceding Javadoc (/**...) comment, comments identified in the following way are considered as belonging to a program element (class or member): [] All preceding Javadoc comments [] Closest preceding comment regardless of type [] All preceding comments not separated from element by a blank line [] All preceding comments starting with { } [] All preceding comments not starting with { } When not allocated by the above rules: [] Closest succeeding comment regardless of type [] All succeeding comments not separated from element by a blank line [] All succeeding comments starting with { } [] All succeeding comments not starting with { } All other comments are considered as belonging to the file itself rather than any program element and will as far as possible not be affected or included when contained elements are moved, copied, or removed.
My assumption would be that bug 54204 will be done for M9 but your last proposal about new options to modify heuristic will be postponed after 3.0. Of course this need to be confirmed and will update milestone accordingly. I will also appreciate feedback on new heuristic proposal, thx
Already sent attached a comment to this affect to Bug 54204 but for the sake of completness: I believe that the focus on relating as many comments as posssible to one node or another is counterproductive from the JDT user's point of view. At all times, even when using refactoring commands or drag&droping program elements, when I edit my code, I naturally want to know exactly what happens with it. Complicated heuristics with tricky corner cases will simply not do. Robustness is the issue, and, as always, doing as little as possible the key. Therefore I believe in a default heuristic much simpler than todays with an added possiblity for the individual user to introduce additional rules to support a specific programming (code formating) style. This was the reason for my options proposal.
Position tuning is deferred post 3.0 (too risky)
Reopen as LATER is deprecated...
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. If you have further information on the current state of the bug, please add it. 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.
