ApexDoc Comments aren't aligned

[Javier García Manzano]

I'm not 100% sure if this is due to the ApexDoc feature added in 1.8.0.2 version of IC, or if it's some kind of misconfiguration in IntelliJ.

Yesteday, before updating the version, comments where alligned, but today they output like this:

[Scott Wells]

Javier, it's certainly a result of 1.8.0.2. Can you explain how it became misaligned? Did it happen immediately after typing /** Enter, or was it in response to reformatting? What version of IntelliJ are you using? I had to jump through some significant hoops to make this work with both recent versions and older supported versions (for some reason I'm still supporting all the way back to IDEA 12 which was released in 2012!). Anything special required to reproduce, or just try to add an ApexDoc header to an existing method?

[Dzmitry Maksimau]

I have a similar problem. When I make a copy-paste "method with ApexDoc". As a result, I get the same as in the screenshot above (Idea 14).

[Scott Wells]

Aha! Is everyone who is having this problem using tabs vs. spaces for indentation by chance? Either way I'll get a fix out very soon, but I'm wondering if the issue is primarily that.

[Javier García Manzano]

Hi @RoseSilverSoftware , I'm using the 2017.2.3 build of IntelliJ. And regarding the bug, it's as you said, after typing /** Enter. Regarding your last question,I can't say because I share the repo and some colleagues use spaces while I prefer tabs and sometimes I reformat it and other times I don't.

[Scott Wells]

Yeah, I'm 99% sure it's a tabs vs. spaces thing. Unfortunately on this I'm having to do the line-level formatting myself...too long to explain, but I can't use what IntelliJ offers for other formatting. I just looked and I'm just counting white spaces from beginning of line on the anchor element and then inserting that number of spaces. If you're using tabs, you'd get exactly what your screenshot shows. I'll get a fix out today if I can. Sorry for not testing with tabs properly here!

[Javier García Manzano]

@RoseSilverSoftware don't worry, as we say in Spain, it happens even in the best of families! It's still a great product :)

[Derek Wiers]

This may be more of a feature request thing, but would it also be possible to customize the functionality to do this:

    /**
    * @description This is the description
    * 
    * @param param      Param description
    */

(note the alignment of the *)?

[Derek Wiers]

^^^ of note I'm using tabs, not spaces these days since spaces count toward char limits in Apex

[Scott Wells]

Derek, I'm going to add ApexDoc config to the Apex formatter config in 2.0 including whether to add blank lines before @param and @return, etc. I can add an option not to include the extra space then. Aside from fixing the tab alignment issue (and any other bugs in the current implementation), I'm trying to wrap up new feature development in the 1.x line so I can release 2.0 very shortly.

[Derek Wiers]

Cool, thanks for the update. Have you announced a release date and/or feature set for 2.0 yet? If so, I haven't found it...

[Scott Wells]

Planning to announce details very soon. I can speak pretty solidly from a feature set standpoint right now, though.

I've already implemented multiple refactorings including rename, introduce variable, and smart delete, and I plan to add introduce constant and move (primarily class variables/methods to start) before releasing if possible. I've added a number of client-side code inspections including unused declaration, unresolvable reference, declaration/usage case mismatch, keyword case mismatch, and control flow statement without braces, most of which include intentions (quick fixes) as well. I'm going to integrate the new Apex Language Server for more thorough client-side semantic code validation, and I plan to add a few smart code generation features such as implement/override methods and generate constructors/accessors. That's what I'm shooting for in the initial release, and as always it will expand from there with more refactorings, code inspections/intentions, etc. I have a ridiculously long list against which I'm working!

Full support for ApexDoc was going to be a 2.0 feature, but when I did the minimal version for 1.x described above, I just felt like it wasn't really "done" and kept going. At this point the main thing missing is formatter config, so I'm holding that until 2.0. I'll also be rolling the pre-release SFDX support into the official 1.x build in the next week or so as the last major 1.x feature.

If all goes well I'll announce pricing (including upgrade) and timing for the release in the next couple of weeks.

[Scott Wells]

FYI, I just implemented a fix for the tabs vs. spaces issue (and it was easily reproducible). I'll post an updated build either later today or tomorrow morning.

[Scott Wells]

Delivered in 1.8.0.3. Please let me know if it's not working as expected when using tabs now.

[Dzmitry Maksimau]

My problem is still reproduced. I use only spaces.

[Scott Wells]

Dzmitry, can you provide an example of a simple class in which this occurs plus exactly what you're doing in that class when it happens? That will make it much easier for me to reproduce and fix. Thanks!

[Wim Velzeboer]

Thank you Scott for solving this issue so quickly!

It now works with tab-indens perfectly!

[Dzmitry Maksimau]

Scott, my step to reproduce: 1. Use only space 2. Copy ApexDoc + method 3. This copy insert into an empty string (work correct), but if the string contains at least one space (only first ApexDoc line and method display correctly, the rest of ApexDoc as in the screenshot above) Thank You!

[Scott Wells]

Thanks, Dzmitry. I'll let you know if I can't reproduce, but once I do it should be easy enough to fix. I'll let you know soon either way!

[Scott Wells]

Reopening to look into Dzmitry's reported issue.

[Scott Wells]

Dzmitry, I was able to reproduce this by pasting after existing whitespace in a line. Basically it looks like it's taking into account that whitespace when determining the indent to use. Should be simple to fix. Thanks again for providing the detailed steps to reproduce!

[Scott Wells]

I believe this is resolved with the new ApexDoc formatter in 2.1.1.1. Please feel free to reopen if you still see this issue.

[Piotr Kożuchowski]

@Scott Wells

Apex docs are broken for me since last update.

When I have some method without javadoc and tyoe /**<enter>, it looks like this:

Indention is broken.

‌

If I do the same for variable, it looks like this:

IntelliJ IDEA 2019.3.4 (Ultimate Edition)
Build #IU-193.6911.18, built on March 17, 2020

IC2 ver. 2.1.1.2

I use spaces for indention, but as you can see the indention is only preserved for 2 first lines.

[Scott Wells]

Hi, Piotr. Can you please provide your Apex formatter settings, specifically the values from the Tabs and Indents tab and the ApexDoc tab? Screenshots of those two should be sufficient.

[Piotr Kożuchowski]

‌

Not sure if I unchecked “Enable ApexDoc formatting” option or was it disabled since beginning, I don’t remember that, but it seems to fix the formatting

On the other hand, it injects @params in javadocs that I’ve ommited purposely for being too obvious. Is there any way to disable that behavior?

[Scott Wells]

Not at present, no, though previously typing /**<enter> would have also added @param and @return tags as appropriate for the documented declaration.

The goal of the new ApexDoc formatter and static code analyzer is to help lead the author toward properly-formed ApexDoc. As a result, it will add/remove @param and @return tags as appropriate based on the documented declaration.

If you'd like to see other options, feel free to log a separate enhancement request with details on what you'd like to see.

[Piotr Kożuchowski]

Sure, adding/removing @params is another thing - a Feature Request eventually.

But right now, with “Enable ApexDoc formatting” option unchecked, the first 2 lines of javadoc are properly indented while all others are not indented at all. I think all lines should be uniformly indented at the time of generating the doc, irrespectively of the setting. They should keep the indention of “/**”.

[Piotr Kożuchowski]

Also, I’ve noticed just now that javadoc opening “/**” is not formatted properly, even with that option checked, if you don’t have indention at all.

This won’t be indented properly when formatted.

‌

[Piotr Kożuchowski]

There are 2 more things actually that I’ve just noticed:

1. When you hit Ctrl+Z after generating javadoc, it brings back code that wasn’t there before
2. Not sure if that’s a bug, but when you have a method, type /** and hit format instead of enter, it will comment out all your code lines until next javadoc or end of class.

‌

[Scott Wells]

Piotr, I'll take a look at these. The first one you mentioned sounds like a bug. Of the other two you mentioned your most recent comment, the first one is a known behavior since ApexDoc support was first added--it's an unfortunate aspect of how I had to implement it without a full first-class ApexDoc parser registered with the IDE--and the second is just because right now IC either expects you to type /**<enter> or use the code intention to create the doc comment.

[Luke Kozakewycz]

Hi - just want to point out that I have also been having this issue. It turns out that having this automated really speeds up documenting code! Hope to see a fix soon.

My problem is pressing enter creates the header comments correctly, but when you had a new line for the description, the indentation is off by one character.

Thanks Scott!

[Scott Wells]

Hey, Luke. Yeah, I'm going to take a look at these issues soon...probably later this week or early next week. I need to wrap up my current set of new features before I can turn my attention elsewhere. I'll let you all know what I find when I start on these.

[Scott Wells]

I've committed fix for Piotr's issue with comments not formatting properly when starting them in the first editor column and Luke's issue with the indentation being off by one character. Those two fixes will be included in the next build.

The Ctrl+Z behavior described by Piotr has been there all along and is actually quite difficult to fix, so that one won't be addressed anytime soon unfortunately. The second issue described in that same comment where you type /** and then the format keyboard shortcut instead of Enter has the exact same behavior in Java which is expected, so that also won't be fixed.

[Scott Wells]

2.1.1.6 has been released with the two fixes described in my previous comment.