Community
Participate
Working Groups
We are using the code formatter (org.eclipse.jdt.core. formatter.CodeFormatter) from within a code generating plugin and everything works fine except it does NOT format comments and Javadoc according to the preferences setting in ">Java>Code Style>Code Formatter" (Edit profile, tab "comments").
This is a known limitation that will be fixed once the comment formatter will be fully integrated in the code formatter. You can however format each javadoc comment using the K_JAVADOC kind.
We've tried that already on the whole source file with the effect that all source became javadoc. I understand you propose to format the javadoc parts separately one by one? While this seems obviously possible, it's quite a burden for the developer, isn't it? Wouldn't it be possible to call formatting with K_JAVADOC kind for a whole document but the Eclipse formatter applying such a formatting operation only to javadoc parts of the document (that's what I've expected when formatting a second time on my document with K_JAVADOC)? This would be a great help!
I admit this is a burden for the developer, but this would be a temporary workaround. The kind needs to correspond to the specified source. So K_JAVADOC can only be used for a source that is a javadoc comment. Once the comment formatter is fully integrated within the code formatter, passing the whole compilation unit will format the javadoc comments as expected. I am not sure this could be done in 3.1.1 pass. I'll investigate the risk of such a change.
Thanks for investigating the integration with the formatter. We can live with the workaround (or not providing Javadoc formatting as a result of our generator) for a while when we know it will be integrated with the formatter in the foreseeable future. I've just posted an enhancement request (https://bugs.eclipse.org/bugs/show_bug.cgi?id=102784) in this context which would also touch the question of integrating the functionality of the editors formatter and the org.eclipse.jdt.core.formatter.CodeFormatter. For us it is quite important that the result of manually formatting from within the editor (Cntrl+Shift+F) does not differ from the formatting of our generator. I believe this is what most people expect anyway (before they detect the differences as we just did). But VERY IMPORTANT in this case is the distinction between JAVADOC formatting and COMMENT formatting. I would be grateful if you could look at our enhancement request and give me on that a brief feedback as well. Many thanks. Andreas
Hi Olivier, Can you say when this will happen? I'm strugling with it because of Bug 154109.
I must work on this for 3.4. Formatting should all be done at the core level.
*** Bug 173289 has been marked as a duplicate of this bug. ***
Eric, please ask Olivier for is work in progress on this subject and continue from there.
(In reply to comment #8) Olivier, waiting for your input - thanks
Related issues in bug 93644 and bug 204091
Created attachment 84153 [details] [incomplete patch] based on Olivier's work, uploaded to save work in progress
see bug 128653
see (fixes) bug 198963
Created attachment 90863 [details] intermediate patch incomplete patch, but: - passes all formatter tests - disables the specific re-formatting of Javadoc comments (as these are parsed / formatted while formatting the CU)
Created attachment 91365 [details] [intermediate patch] - cleaned up the Scribe UI reformatting disabled - Still passes all the formatter tests
In order to avoid breaking existing clients, the new formatter behavior (i.e. format comments while formatting the whole compilation unit) would be activated only if a specific flag was set. This flag would be defined in CodeFormatter and named 'F_INCLUDE_COMMENTS'and clients would have to combine it with existing CodeFormatter.K_COMPILATION_UNIT or CodeFormatter.UNKNOWN kinds to see the fix for this bug activated... Here's its complete new API changes proposal on org.eclipse.jdt.core.formatter.CodeFormatter: /** * Flag used to include the comments during the formatting of the code * snippet. * <p> * This flag can only be combined with following kinds: * <ul> * <li>{@link #K_COMPILATION_UNIT}</li> * <li>{@link #K_UNKNOWN}</li> * </ul> * </p><p> * Note also that it has an effect only when the option * {@link DefaultCodeFormatterConstants * #FORMATTER_COMMENT_FORMAT_JAVADOC_COMMENT} * is set to {@link DefaultCodeFormatterConstants#TRUE} while calling * {@link #format(int, String, int, int, int, String)} or * {@link #format(int, String, IRegion[], int, String)} methods * </p><p> * For example, with the Eclipse default formatter options, the formatting of * the following code snippet using {@link #K_COMPILATION_UNIT}: * <pre> * public class X { * /** * * This is just a simple example to show that comments will be formatted while processing a compilation unit only if the constant flag <code>F_INCLUDE_COMMENT</code> flag is set. * * @param str The input string * */ * void foo(String str){}} * </pre> * will produce the following output: * <pre> * public class X { * /** * * This is just a simple example to show that comments will be formatted while processing a compilation unit only if the constant flag <code>F_INCLUDE_COMMENT</code> flag is set. * * * * @param str The input string * */ * void foo(String str){ * } * } * </pre> * Adding this flavor to the kind given while formatting the same source * (e.g. {@link #K_COMPILATION_UNIT} | {@link #F_INCLUDE_COMMENTS}) * will produce the following output instead: * <pre> * public class X { * /** * * This is just a simple example to show that comments will be formatted * * while processing a compilation unit only if the constant flag * * <code>F_INCLUDE_COMMENT</code> flag is set. * * * * @param str * * The input string * */ * void foo(String str){ * } * } * </pre> * </p><p> * <i><u>Note</u>: Although we're convinced that the formatter should * always include the comments while processing a * {@link #K_COMPILATION_UNIT kind of compilation unit}, we * have decided to add a specific flag to fix this formatter incorrect behavior. * This will prevent all existing clients using the {@link #K_COMPILATION_UNIT} * kind to be broken while formatting.</i> * </p> * @since 3.4 */ public static final int F_INCLUDE_COMMENTS = 0x1000; Note that CodeFormatter.UNKNOWN and CodeFormatter.K_COMPILATION_UNIT specification will be updated to include this new possible combination: /** * Unknown kind * * Note that since 3.4, the {@link #F_INCLUDE_COMMENTS} flag can be added * to this constant in order to get the comments formatted if a * compilation unit is processed. */ public static final int K_UNKNOWN = 0x00; /** * Kind used to format a compilation unit * <p> * Note that using this constant, the javadoc comments are only indented while * processing the compilation unit. * </p><p> * <b>Since 3.4</b>, if the corresponding comment option is set to * <code>true</code> then it is also possible to format the comments on the fly * by adding the {@link #F_INCLUDE_COMMENTS} flag to this kind of format. */ public static final int K_COMPILATION_UNIT = 0x08;
The behavior of headless formatter (accessible through org.eclipse.jdt.core.formatter.CodeFormatterApplication) would also be modified. For this "batch" formatting, no additional flag would be defined, hence clients would need to unset the comments formatting corresponding options to avoid to have the comments formatted while processing the whole compilation.
Created attachment 95837 [details] Proposed patch Note that this patch currently only fixes the problem for Javadoc comments. Clients still needs a second pass for line and block comments. This should also be fixed soon on a separated bug...
Created attachment 96012 [details] Released patch Here's the final changes released to fix this bug...
Released for 3.4M7 in HEAD stream.
(In reply to comment #18) > Note that this patch currently only fixes the problem for Javadoc comments. > Clients still needs a second pass for line and block comments. This should also > be fixed soon on a separated bug... The separate bug is bug 227043
How does it work when formatting only a method using org.eclipse.jdt.core.formatter.CodeFormatter.K_CLASS_BODY_DECLARATIONS that has a javadoc comment or any type of comments inside the method body? What about statements with block or line comments in the middle using K_STATEMENTS?
(In reply to comment #22) > How does it work when formatting only a method using > org.eclipse.jdt.core.formatter.CodeFormatter.K_CLASS_BODY_DECLARATIONS that has > a javadoc comment or any type of comments inside the method body? > > What about statements with block or line comments in the middle using > K_STATEMENTS? > Nothing has changed in this area. The F_INCLUDE_COMMENTS only applies when K_COMPILATION_UNIT and K_UNKNOWN kinds are used. That means the formatter still only indents the comments and aligns the stars for javadoc and block comments when the other constant kinds are used.
(In reply to comment #23) > K_COMPILATION_UNIT and K_UNKNOWN kinds are used. That means the formatter still > only indents the comments and aligns the stars for javadoc and block comments > when the other constant kinds are used. I don't see why we have this limitation.
(In reply to comment #24) > I don't see why we have this limitation. > Just a time limitation. The implementation is trivial but I had no time to implement tests around these constants to verify that everything works well with the new implementation...
Since the specification of the new constant will be a contract, this can never be added in the future.
Verified for 3.4M7 using I20080429-0100
*** Bug 111270 has been marked as a duplicate of this bug. ***
I've to get back to the start of this Case. Oliver Thomann as the very first feedback to my original request of this case answered: > This is a known limitation that will be fixed once the comment formatter will > be fully integrated in the code formatter. We are still experiencing sometimes different formatting results between a "manual" formatting (CNTRL+Shift+F) and a formatting which was done by our Code-Generator through the Eclipse Plugin API - always related to either Javadoc formatting and/or block comment formatting. I think to remember an earlier answer in the context of this or possibly an even older case, that the editor's implementation of the formatter (CNTRL+Shift+F) and the Plugin-API implementation of the formatter are still different (or at least comment formatting is not yet fully integrated on "both sides"). As a consequence, even some formatting preferences have not yet had been fully integrated in the "Plugin implementation" of the formatter. Is this still the case or since which release do we possibly (hopefully) have an identical formatter implementation for the Editor (CNTRL+Shift+F) and the Plugin API usage? I am very grateful for a short answer to this question, because we're really struggling to sort out these different formatting results. May be it's still due to different or notyet fully integrated implementations of the formatting? Thanks a lot! Andreas
(In reply to comment #29) > We are still experiencing sometimes different formatting results between a > "manual" formatting (CNTRL+Shift+F) and a formatting which was done by our > Code-Generator through the Eclipse Plugin API - always related to either > Javadoc formatting and/or block comment formatting. What build are you using ?
We've released our Framework with the related Eclipse Plugins for Eclipse 3.4.1 but inoffcially also tested with subsequent 3.4.n versions. I don't know the exact Eclipse Build the customer is using, but definitely can check that. On the other side, if you could tell since which Eclipse Release the formatter possibly has been fully integrated (or not yet within 3.4.n?) - we may quickly have an indication whether this can be part of our problem or not. Answer about the exact version/build will take until tomorrow, because I can't get the customer before. So an initial indication since which Release the formatter may have been fully integrated could help - otherwise I post the exact build information asap. Thanks!
Besides the integration there were still many formatter differences/bugs that Frédéric fixed in 3.5 and 3.6, so it's likely that you still see issues when using 3.4.2 or older builds. Since there are no further maintenance builds for 3.4 or 3.5, the best you can do is to switch to 3.6 M6 and test whether you still see the issue and if so, open a new bug with steps to reproduce it.
Thank you for the feedback re 3.4.x/3.5/3.6. We and particularly our customer who reported the problem with different formatting results from the Editor (CNTRL+Shift+F) and our Code Generator (formatting through Eclipse Plugin API) are using 3.4.1 currently. The concrete build of our customer is M20080911-1700. We'll definitely look to upgrade to 3.5/3.6 but have to do comprehensive testing of our plugins which can only be aligned with our next release. So just for our understanding, whether we may have to investigate deeper in the current customer case, can you tell me the status of the formatter with 3.4.1-M20080911-1700 regarding the integration between editor and Plugin API: Should the formatter be identical or are there still different implementations or missing integrations of Javadoc/Comment formatting or other parts of the formatter in 3.4.1-M20080911-1700 (irrespective of probably some remaining bugs)?
(In reply to comment #33) > Thank you for the feedback re 3.4.x/3.5/3.6. > > We and particularly our customer who reported the problem with different > formatting results from the Editor (CNTRL+Shift+F) and our Code Generator > (formatting through Eclipse Plugin API) are using 3.4.1 currently. The concrete > build of our customer is M20080911-1700. > > We'll definitely look to upgrade to 3.5/3.6 but have to do comprehensive > testing of our plugins which can only be aligned with our next release. So just > for our understanding, whether we may have to investigate deeper in the current > customer case, can you tell me the status of the formatter with > 3.4.1-M20080911-1700 regarding the integration between editor and Plugin API: > > Should the formatter be identical or are there still different implementations > or missing integrations of Javadoc/Comment formatting or other parts of the > formatter in 3.4.1-M20080911-1700 (irrespective of probably some remaining > bugs)? The formatter should be identical. Bugs existing in 3.4.1 version should not imply a difference between the UI and headless usage of the formatter. So, I strongly suggest that you open a new bug with at least a code snippet exhibiting the differences and also the arguments values used for the headless API call. TIA
