More Javadoc formatting option needed

Answered
Avatar
Permanently deleted user
Created

I need to be able to keep some code excerpt verbatim in the Javadoc of
some class/method.

It should look like that:

  • {@code

  • <bean id="commonProperties"

init-method="init">

  •      <property name="locations">

  •          <list>

  •              <value>classpath:config.properties</value>

  •          </list>

  •      </property>

  • </bean>

  • }


I can't find a way to keep that piece formatted as it is with IDEA
JavaDoc formatting option enabled.

This is in line with the @formatter:off option required for a generic
way of keeping code unaltered by IDAE's formatter.

I don't think it'd be suitable in this case though.

An option in the line of 'Keep @code and @literal content as is' would
probably be better.

rgds

Votes

1

Share

6 comments
Avatar
Alex
Created

Same issue here: we have a lot of code examples in javadoc comments which I'd like to remain untouched when I format source code. I'd like to have support for </pre> tag.

0
Avatar
Egor Klepikov
Created

Do I understand correctly that you'd like one part of the comment to be formatted and the other not?

Note that formatter marker can be changed in Settings/Preferences | Editor | Code Style | Formatter Control settings:

0
Avatar
Alex
Created

Hi Egor Klepikov, thanks for the reminder. It turns out that the formatter markers options were not enabled in my IntelliJ. They all work now as expected in the below example ('destFile = ...' line remains on a separate line rather being pushed back to the previous line to form 'dockerFile { * destFile =...')

/**
 * Default Dockerfile instructions. These can be overridden by subclassing
 * or per build project via 'build.gradle' file:
 * @formatter:off
 * <pre>
 * dockerFile {
 *   destFile = project.file 'Dockerfile' // place Dockerfile in the project root folder
 *   from '...'
 *   runCommand '...'
 * }</pre>
 * @formatter:on
 * For the full list of commands, see {@link com.bmuschko.gradle.docker.tasks.image.Dockerfile}
 */
void instructions(Dockerfile task) {
}

 

Nevertheless, they clutter my javadoc code and I'd still vote for supporting <pre> tags in javadocs, that is, do not format the snippet enclosed in <pre>...</pre> tags in javadoc comments without me having to use format markers at all.

0
Avatar
Egor Klepikov
Created

In your case, you can try adding <pre> tag as a marker. For example:

 

0
Avatar
Alex
Created

Right! That's not a bad idea but certainly not a solution either: '// formatter:off/on' blocks are used already on other places through out the (non-javadoc) code. In which cases, using '// <pre>' just looks odd.

0
Avatar
Egor Klepikov
Created

Thanks for pointing it out. I've raised a new issue at https://youtrack.jetbrains.com/issue/IDEA-257227. Feel free to vote for it to increase priority.

0

Please sign in to leave a comment.