9

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?

Kristóf Marussy
  • 1,122
  • 7
  • 15

3 Answers3

9

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 -->
*
*
*/
user3528877
  • 91
  • 1
  • 3
  • Thanks. Only the [// @formatter:off] syntax worked for me. I'm using Eclipse STS 3.6.1.RELEASE – A. Masson Feb 03 '15 at 23:07
  • 2
    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 `` 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 :-) – Amos M. Carpenter Feb 26 '18 at 03:46
  • 1
    '@formatter:off' and '@formatter:on' worked out of the box in Eclipse 2019-03 for me within javadoc comments – Deepak Apr 23 '20 at 07:15
1

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

Dave
  • 4,388
  • 2
  • 35
  • 57
  • 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. – Kristóf Marussy Jan 15 '13 at 19:14
  • Likewise, based on empirical testing, you cannot selectively disable formatting for non-header block comments, e.g.: /* comment */ – Will Sep 06 '13 at 18:56
  • [This answer](http://stackoverflow.com/a/1025619/1135954) explain a work-around by including the html tags. – mtk Nov 03 '13 at 17:32
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.

Mahmoud K.
  • 4,822
  • 1
  • 25
  • 38