4 ms·

I may have one of the single dumbest reasons every to not be able to use IntelliJ as my primary dev environment: their comment/Javadoc formatter isn't as robust

by rkalla 15y ago

I may have one of the single dumbest reasons every to not be able to use IntelliJ as my primary dev environment: their comment/Javadoc formatter isn't as robust as Eclipse's. I am very verbose commenter for both other people coming behind me (in closed or open source software[1]) as well as myself a year down the road going back through thick code and needing to get back up to speed on it. Because of this I frequently use HTML formatting in my Javadoc (lists, code snippets, etc.) and find Eclipse's Javadoc formatter more or less perfect. It breaks lines exactly like I want it to, leaves blank lines entact where I want it to, etc. I've attempted to file bugs for IntelliJ over the years to refine their Javadoc formatter and they have been fixed, but it still misses the boat on complex single, multi-line or Javadoc comments that requires hand-editing. I know it's silly, I just can't get over that. I also find the module/web/deployment/artifact model untenable; but even that I could get around if I had an effective formatter. (FWIW the Eclipse/WTP model is just as stupid when it comes to J2EE project modeling, so no one wins that battle) [1] http://www.thebuzzmedia.com/downloads/software/imgscalr/javadoc/org/imgscalr/Scalr.html http://www.thebuzzmedia.com/downloads/software/imgscalr/java...

BasLeijdekkers 15y ago
If you can't get IntelliJ IDEA's JavaDoc formatter to do what you want there exists a plugin which lets you use Eclipse for formatting call Eclipse Code Formatter: http://plugins.intellij.net/plugin/?idea&id=6546 http://plugins.intellij.net/plugin/?idea&id=6546 I have never used it, so I cannot comment on its quality, but it might be worth a try. However submitting bugs and feature requests with examples would be better. Many reports are fixed quite quickly. I did not manage to find the bugs you filed though: http://youtrack.jetbrains.net/issues?q=%23rkalla http://youtrack.jetbrains.net/issues?q=%23rkalla
- rkalla 15y ago
  Bas thank you for the link; I gave that plugin a try before going back to Eclipse. Unfortunately the workflow of actually using it is terrible for someone that formats frequently (like I do). I can't find older bugs, but the most recent one was this one: http://youtrack.jetbrains.net/issue/IDEA-28895?query=voted+by%3A+rkalla http://youtrack.jetbrains.net/issue/IDEA-28895?query=voted+b... I don't know what happened between the report and the fix in 10.x, but I didn't notice changed behavior. The formatter still didn't wrap correctly for me and indent. For example, take this: /* This is a really long line */ and turn it into: /* * This is a really * long line. */ IIRC what it did was break the line but not prefix it with star, or it prefixed it but put no space between star and the chars... something like that. It also didn't handle longer // comments well from what I remember and most importantly would mangle the HTML embedded in my Javadoc comments. These are little touches that Eclipse takes care to handle... like ul-li lists inside of Javadoc that it will leave as a list and not try and compact down into a run on sentence. Or things like p-tags formatted nicely as paragraphs. I literally just want the default formatter from Eclipse in IJ and I'd be a happy camper. I am surprised more people don't notice these discrepancies, but I don't want to be the only one pestering the IJ team for these fixes. They have plenty of other things to work on. As I said I like to write a lot of comments; so I notice this more than most. I don't think I represent the norm here.
kittxkat 15y ago
Holy wow, your documentation style is truly awesome. Clear and crisp, just how it should be. I wanna have it's babies.
- rkalla 15y ago
  Thanks kitt, I really try hard to write enough documentation that no one (including me) is confused by my code if there are interested in understanding it.

by rkalla 15y ago

BasLeijdekkers 15y ago

If you can't get IntelliJ IDEA's JavaDoc formatter to do what you want there exists a plugin which lets you use Eclipse for formatting call Eclipse Code Formatter: http://plugins.intellij.net/plugin/?idea&id=6546 http://plugins.intellij.net/plugin/?idea&id=6546 I have never used it, so I cannot comment on its quality, but it might be worth a try. However submitting bugs and feature requests with examples would be better. Many reports are fixed quite quickly. I did not manage to find the bugs you filed though: http://youtrack.jetbrains.net/issues?q=%23rkalla http://youtrack.jetbrains.net/issues?q=%23rkalla

rkalla 15y ago
Bas thank you for the link; I gave that plugin a try before going back to Eclipse. Unfortunately the workflow of actually using it is terrible for someone that formats frequently (like I do). I can't find older bugs, but the most recent one was this one: http://youtrack.jetbrains.net/issue/IDEA-28895?query=voted+by%3A+rkalla http://youtrack.jetbrains.net/issue/IDEA-28895?query=voted+b... I don't know what happened between the report and the fix in 10.x, but I didn't notice changed behavior. The formatter still didn't wrap correctly for me and indent. For example, take this: /* This is a really long line */ and turn it into: /* * This is a really * long line. */ IIRC what it did was break the line but not prefix it with star, or it prefixed it but put no space between star and the chars... something like that. It also didn't handle longer // comments well from what I remember and most importantly would mangle the HTML embedded in my Javadoc comments. These are little touches that Eclipse takes care to handle... like ul-li lists inside of Javadoc that it will leave as a list and not try and compact down into a run on sentence. Or things like p-tags formatted nicely as paragraphs. I literally just want the default formatter from Eclipse in IJ and I'd be a happy camper. I am surprised more people don't notice these discrepancies, but I don't want to be the only one pestering the IJ team for these fixes. They have plenty of other things to work on. As I said I like to write a lot of comments; so I notice this more than most. I don't think I represent the norm here.

kittxkat 15y ago

Holy wow, your documentation style is truly awesome. Clear and crisp, just how it should be. I wanna have it's babies.

rkalla 15y ago
Thanks kitt, I really try hard to write enough documentation that no one (including me) is confused by my code if there are interested in understanding it.