Disabling Eclipse code formatting for part of a javadoc
Asked Answered
W

3

12

I have a Java class for which part of the javadoc is actually generated as part of the build process: the return value of a method (a static String value) is inserted into the source file, much like $Revision: $ tags work in some version control software.

While this behaviour may be questionable, such duplication of information is required by the framework I use (WEKA machine learning library). I would like Eclipse's code formatter not to interfere with the generated comments. I am using the Eclipse Indigo release.

I can turn the formatter on/off with special comments //@formatter:on and //@formatter:off. However, the @formatter tags are only functional in 'normal' comments, not in javadoc comments. Obviously, they could be easily confused for javadoc tags. This means I cannot turn off the formatter (for example, automatic line breaking) for the generated part of the javadoc comment, and leave it on for the rest, because the @formatter directives must be placed around the javadoc comment.

It there a workaround to toggle code formatting inside javadoc comments?

Wherever answered 18/8, 2012 at 12:38 Comment(0)
J
1

You can disable formatting for the header, but I don't believe you can selectively disable formatting for nonheader javadoc comments.

Jacobjacoba answered 18/8, 2012 at 13:38 Comment(3)
Quite a long time has passed since I asked this question. Anyways, I accept this answer since it is, as a matter of fact, entierly correct.Cyclone
Likewise, based on empirical testing, you cannot selectively disable formatting for non-header block comments, e.g.: /* comment */Divulge
This answer explain a work-around by including the html tags.Phelips
I
13

Been a while since this was asked/answered and helped me refine the following answer, hopefully additionally useful. I use this alternative as I wanted to run Javascript in Javadocs.

Eclipse provides the @formatter:off and @formatter:on which needs to be enabled via Windows->Preferences->java->code style->formatter:::edit button::: tab "off/on tags". They may be used in any comments.

Around the doc stuff

// @formatter:off
/**
* javadoc
*/ 
// @formatter:on

But when you want the formatter off within the javadoc use the @formatter:xxx within html comments <!-- xxxxx --> to indicate what you are trying to do. Use the <code>...</code> bloack to ensure no formatting and the inclusion of code as javascript.

Editted the code statements in the example as I wanted this to work on eclipse and netbeans. I found the formatter:off work but then stopped working on a different version of eclipse (yes I use multiple IDE versions).

/** 
* <br><!-- @formatter:off -->
* <code>
* <script type="text/javascript">
* // hash structure for holding variable as name and its text
* var hashText = {};
*  
* // function causes a hyper-link to be created
* function insertLink(varName, text){
*    var link22;
*  
*    hashText[varName] = text;
*  
*    link22 = '<a href="./ConsoleCapture.html#' + varName + '">' + hashText[varName] + '</a>';
*       
*    document.write(link22);
* }
* function insertLinkA(varName){
*    var link22;
*
*    link22 = '<a href="./ConsoleCapture.html#' + varName + '">' + hashText[varName] + '</a>';
*
*    document.write(link22);
* }
*      
* function setLinkPoint(varName, text){
*     hashText[varName] = text;
*      
*     document.write('<a id="' + varName + '"><U>' + hashText[varName] + '</U></a>');
* }
*      
* function setLinkPointA(varName){
*    document.write('<a id="' + varName + '"><U>' + hashText[varName] + '</U></a>');
* }
* </script>
* <code>
* <!-- @formatter:on -->
*
*
*/
Innocent answered 13/4, 2014 at 12:43 Comment(3)
Thanks. Only the [// @formatter:off] syntax worked for me. I'm using Eclipse STS 3.6.1.RELEASETremulous
Somewhere between then and 2018, the autoformatter is controlled by using autoformat:off instead of formatter:off (and on), but the principle still works. My initial thought was putting in a <span style="display: none;"> or something to stop the autoformatter instruction from showing up in the javadoc, but of course the HTML comment idea is much better, so thanks :-)George
'@formatter:off' and '@formatter:on' worked out of the box in Eclipse 2019-03 for me within javadoc commentsNarwhal
J
1

You can disable formatting for the header, but I don't believe you can selectively disable formatting for nonheader javadoc comments.

Jacobjacoba answered 18/8, 2012 at 13:38 Comment(3)
Quite a long time has passed since I asked this question. Anyways, I accept this answer since it is, as a matter of fact, entierly correct.Cyclone
Likewise, based on empirical testing, you cannot selectively disable formatting for non-header block comments, e.g.: /* comment */Divulge
This answer explain a work-around by including the html tags.Phelips
F
0

I encountered the same problem and changing @formatter:off to FORMATTEROFF did the trick for me.

the idea is to avoid using @ in the on/off tag.

Now I can disable the formatter around a part of a javadoc.

Flagitious answered 3/11, 2020 at 11:25 Comment(0)

© 2022 - 2024 — McMap. All rights reserved.