Is there a way to make Eclipse's built-in Java code formatter ignore comments? Whenever I run it, it turns this:
/*
* PSEUDOCODE
* Read in user's string/paragraph
*
* Three cases are possible
* Case 1: foobar
* do case 1 things
* Case 2: fred hacker
* do case 2 things
* Case 3: cowboyneal
* do case 3 things
*
* In all cases, do some other thing
*/
into this:
/*
* PSEUDOCODE Read in user's string/paragraph
*
* Three cases are possible Case 1: foobar do case 1 things Case 2: fred
* hacker do case 2 things Case 3: cowboyneal do case 3 things
*
* In all cases, do some other thing
*/
I have already played around with the Windows > Preferences > Java > Code Style > Formatter settings but can't find one for keeping comment formatting. I'm using Eclipse 3.4.0.
There is another solution that you can use to suppress the formatting of specific block comments. Use /*- (note the hyphen) at the beginning of the block comment, and the formatting
won't be affected if you format the rest of the file.
/*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
* one
* two
* three
*/
Source: http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141999.html#350
Update 2010, as pointed by the OP and in this answer, the special string // #formatter:off in Eclipse 3.6 is enough.
It was not available at the time of the question.
Original answer: June 2009, Eclipse 3.4/3.5
With the Java Formatter (Windows > Preferences > Java > Code Style > Formatter), you can create a new Formatter profile.
In the Comments tab (in eclipse3.5), you can make sure, in the "Javadoc comment settings", to uncheck "Format HTML tags".
Check also the "Never join lines" in the "General settings" section.
Then your comment should be written as:
/**
* PSEUDOCODE
* Read in user's string/paragraph
*
* Three cases are possible:
* <dl>
* <dt>Case 1: foobar</dt>
* <dd> do case 1 things</dd>
* <dt>Case 2: fred hacker</dt>
* <dd> do case 2 things</dd>
* <dt>Case 3: cowboyneal</dt>
* <dd> do case 3 things</dd>
* </dl>
* In all cases, do some other thing
*/
Note: I have made a Javadoc comment, and not a simple comment, as I believe a comment with that much text in it may be better placed in front of a method. Plus, Javadoc sections have more formatting parameters to play with.
If it is in front of a method (true Javadoc), the HTML tags <dl>, <dt> and <dd> will help to present it properly within the Javadoc view.
I just learned from a co-worker that Eclipse offers special formatting tags that can be used for this:
// #formatter:off
/*
* ╔════════╦═══════╦══════════╗
* ║ Month ║ Sales ║ Position ║
* ╠════════╬═══════╬══════════╣
* ║ June ║ 44k ║ 2nd ║
* ║ July ║ 39k ║ 2nd ║
* ║ August ║ 49k ║ 4th ║
* ╚════════╩═══════╩══════════╝
*
* This comment shouldn't be formatted, and will now be ignored by the formatter.
*/
// #formatter:on
Note that you may need to manually enable this feature through the Preferences menu → Java > Code Style > Formatter, clicking on Edit, selecting the Off/On Tags tab and checking Enable Off/On tags (source).
A quick Google for the string #formatter:off brought me to this other SO answer, which mentioned this feature in the context of disabling the formatter for code blocks. I've confirmed that it works for line comments, "normal" block comments and Javadoc block comments as well.
Another possibility is to use HTML's <pre> in Javadoc:
/**
* <pre>
* this
* is
* kept
* as
* is
* </pre>
*/
At least this is how I tend to embed my ASCII-art in source code comments :)
Surround the specific text with <pre> </pre> tags.
In Eclipse 3.4: Preferences, Java->Code Style->Formatter, then edit profile, comments tab. There's a bunch of options there for controlling comment formatting.
one workaround is to add pre tag for the comments that you don't want eclipse to format
/**
* <pre>
* this part
* is
* out of
* format
*
* </pre>
*/
If you want to supress formatting in eclipse, you can always wrap content that is intended to NOT TO BE FORMATED into <pre>UNFORMATTED CONTENT</pre> tag. Javadoc formatter will detect that tag, and leave everything between that tags unformatted.
Pros:
Rest of Javadoc is still formatted
Javadoc's html output will be "unformatted" as well because of pre tags
Cons:
Not seeing one
Try this one. This worked for me.
With the Java Formatter (Windows > Preferences > Java > Code Style > Formatter), you can create a new Formatter profile from existing and then edit it.
If Eclipse doesn't allow to save this then create a new one and save in that.
It is language-dependent.
For example, if working with javascript, you would go to "Window -> Preferences -> Javascript -> Code Style -> Formatter" and then edit the formatter options.
Edit (reflecting changesin OP Questions
For editing java code formatting, go to
"Window -> Preferences -> Java -> Code Style -> Formatter"
At the top of the panel you will see
Active Profile:
Eclipse [built-in]
From there you have one button to the right, "Edit", and two below, "New..." and "Import...".
I would recommend Editing the existing profile.
In the edit profile dialog, there are a series of tabs along the top. The last tab is "Comments". To completely disable comment formatting, uncheck "Enable Javadoc comment formatting", "Enable block comment formatting", "Enable line comment formatting", and "Enable header comment formatting".
You can change this in
Windows - Preferences - Java - Code Style - Formatter,
than click the Edit.. button, find Comments,
choose the Never Join Lines.
Then, it should be OK.
Related
I know the shortcut Ctrl+shift+A in VS Code Linux to insert the multiple lines comment, but it just insert like this:
/*
my comment
my code i want to hide
etc
*/
How to get a comment like this?
/**
* my comment
* my code i want to hide
* etc
*/
If I want to get comment like above, I need to insert manually like this
/**
*/
And every time I hit "Enter" inside that comment, VS Code automatically insert * like this
/**
*
*
*
*
*
*/
It looks like that kind of comment is supported in VS Code,
But I dont know the short cut to insert the new one without typing manually.
Anyone know the answer ? Thanks,
UPDATE : VS CODE has update about this, more info : https://code.visualstudio.com/docs/languages/javascript#_jsdoc-support
When you type /** VS code will know what you want and show like this
hit enter and move your code inside that comment block
Look like there is no shortcut key for this till now, and if we want to that kind of comment style, we need to do it manually by typing this:
/**
*/
and hit "Enter" inside that comment
I have set the template for "Types" to be:
/** $$Id$$
* $$Author$$
* $$Revision$$
*
* ${cursor}
*/
However the ${cursor} isn't working as it ought to, you can see here ( http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Fconcepts%2Fconcept-template-variables.htm - top of the first table) how ${cursor} should work.
When I use this template (by typing /** and then pressing enter) I get the following (where | denotes the cursor position)
/**
* |$Id$
* $Author$
* $Revision$
*
*
*/
How can I fix this, or if I am at fault, how can I get the desired behaviour?
The help does not make it very clear but the variables list you reference only applies to the 'Java > Editor > Templates' templates and not to the 'Java > Code Style > Code Templates'.
There is a much more restricted list for variables for the Code Templates which does not include ${cursor}.
Only the variables shown by the 'Insert Variable...' button of the Edit Template dialog are available.
I made documentation for my SDK, using Doxygen. It contains the list of files, namespaces, classes, types etc. - everything that I placed as Doxygen comments in the code. Now I want to write some general information about SDK (kind of introduction), which is not related directly to any code element. I want to place this introduction on the documentation start page. How can I do this?
Have a look at the mainpage command.
Also, have a look this answer to another thread: How to include custom files in Doxygen. It states that there are three extensions which doxygen classes as additional documentation files: .dox, .txt and .doc. Files with these extensions do not appear in the file index but can be used to include additional information into your final documentation - very useful for documentation that is necessary but that is not really appropriate to include with your source code (for example, an FAQ)
So I would recommend having a mainpage.dox (or similarly named) file in your project directory to introduce you SDK. Note that inside this file you need to put one or more C/C++ style comment blocks.
As of v1.8.8 there is also the option USE_MDFILE_AS_MAINPAGE. So make sure to add your index file, e.g. README.md, to INPUT and set it as this option's value:
INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md
Note that with Doxygen release 1.8.0 you can also add Markdown formated pages. For this to work you need to create pages with a .md or .markdown extension, and add the following to the config file:
INPUT += your_page.md
FILE_PATTERNS += *.md *.markdown
See http://www.doxygen.nl/manual/markdown.html#md_page_header for details.
Following syntax may help for adding a main page and related subpages for doxygen:
/*! \mainpage Drawing Shapes
*
* This project helps user to draw shapes.
* Currently two types of shapes can be drawn:
* - \subpage drawingRectanglePage "How to draw rectangle?"
*
* - \subpage drawingCirclePage "How to draw circle?"
*
*/
/*! \page drawingRectanglePage How to draw rectangle?
*
* Lorem ipsum dolor sit amet
*
*/
/*! \page drawingCirclePage How to draw circle?
*
* This page is about how to draw a circle.
* Following sections describe circle:
* - \ref groupCircleDefinition "Definition of Circle"
* - \ref groupCircleClass "Circle Class"
*/
Creating groups as following also help for designing pages:
/** \defgroup groupCircleDefinition Circle Definition
* A circle is a simple shape in Euclidean geometry.
* It is the set of all points in a plane that are at a given distance from a given point, the centre;
* equivalently it is the curve traced out by a point that moves so that its distance from a given point is constant.
* The distance between any of the points and the centre is called the radius.
*/
An example can be found here
Add any file in the documentation which will include your content, for example toc.h:
# mainpage Manual SDK
<hr/>
# section pageTOC Content
-# #ref Description
-# #ref License
-# #ref Item
...
And in your Doxyfile:
INPUT = toc.h \
Example (in Russian):
scale-tech.ru/luckyBackupW/doc/html/index.html (via web.archive.org)
scale-tech.ru/luckyBackupW/doc/html/toc_8h_source.html (via web.archive.org)
I tried all the above with v 1.8.13 to no avail.
What worked for me (on macOS) was to use the doxywizard->Expert tag to fill the USE_MD_FILE_AS_MAINPAGE setting.
It made the following changes to my Doxyfile:
USE_MDFILE_AS_MAINPAGE = ../README.md
...
INPUT = ../README.md \
../sdk/include \
../sdk/src
Note the line termination for INPUT, I had just been using space as a separator as specified in the documentation. AFAICT this is the only change between the not-working and working version of the Doxyfile.
Fairly straight forward question here. Has anyone figured out how to do a TODO: comment in Eclipse that spans multiple lines? I cannot for the life of me get it to work.
I assign a short title/explanation to the TODO.
This title will be picked up by your IDE and put in the task list for reference.
Then underneath I describe my TODO at length.
The first line will be nicely highlighted in your code, so you can easily recognize your to-do's inline too.
/**
* TODO: Short explanatory title
* Here I start a more lengthy description.
* This can consist of as many lines as you want.
*/
Please try with below lines,
/**
* <pre>
* TODO : You can write very long line here, which will not truncate in task desc.
* </pre>
*/
I don't know if this might help you, but you can also add you own custom task tags under Preferences>Java>Compiler>Task tags. That way you can seperate the default(auto-generated) tags from your own tags which you might find more important to fix then the standard TODO tags.
You can then also configure the Tasks view to only display your own custom tags for instance...
You can create multi line TODO comments like this:
/**
*
* TODO This is the first line
* This is the second line of todo comment
*/
*
* #TODO this is the first line<br>this is the second line
*
Will display with 2 Lines in the tooltips since i've used <br> ;)
Go to preferences → Java → Code style → Formatter → New → give any name → uncheck block commenting.
It seem Eclipse does not mark TODO as comment, it looks for the word "TODO".
So it seem like you have to something like (for now at least):
// TODO:
// TODO:
// TODO:
or
/* TODO:
* TODO:
* TODO:
*/
for multi-line TODOs
i remember there being a way of marking a section of code in eclipse (special comment or annotation?) which made the autoformatter ignore that section. Or I may have drempt this...
Used mainly when I have strings which wrap onto several lines and i don't want the autoformatter to rearrange this.
Since eclipse 3.5 (or 3.6) this is possible:
- Go to project properties -- Java Code Style -- Formatter -- Edit...
- choose the tab marked "Off/On Tags",
- include the tags in comments in your source code, like
/* #formatter:on */
You can wrap the code you don't want auto-formatted between these special comments:
normal code
/* #formatter:off */
strangely laid out code
/* #formatter:on */
normal code
Here's a basic usage example that makes a json string (slightly) more readable:
public class SomeTest {
#Test
public void can_deserialize_json() {
/* #formatter:off */
String json = "" +
"{" +
" \"id\" : 123," +
" \"address1\" : blah," +
" \"shippingInfo\" : {" +
" \"trackingUrl\" : null," +
" \"price\" : 350" +
" }," +
" \"errorMessage\" : null" +
"}";
/* #formatter:on */
MyClass.deserializeJson(json);
}
}
I only know the answer for comments:
Eclipse is smart enough to only re-format the comments where the generated JavaDoc wouldn't change (i.e. where whitespace doesn't matter):
/**
* foo <i>
* bar </i>
*
* <pre>
* foo
* bar
* </pre>
*/
will be reformatted into
/**
* foo <i> bar </i>
*
* <pre>
* foo
* bar
* </pre>
*/
Note how the content of the <pre> tags is not reformatted.
For long String literals, I'd suggest that they might be an indication that you should be externalizing some of them.
I am not sure about the exact feature you're referring to, but you can change the line wrap policy of expressions, which may help you with your strings problem. See:
Window->Preferences->Java->Code Style->Formatter
Click "Edit..." Button
Click "Line Wrapping" Tab
In the tree, choose Expressions->Assignments, then change the indent policy at the bottom of the window.
Of course there are myriad other options inside the formatter, you may find many of those useful as well for other rules, such as where to put your braces, or how to indent control blocks.
I just found this question because I'm also annoyed by the lack of this feature.
A small search showed this question and the following answer:
Stop eclipse from line wrapping?
Eclipse 3.5 supports this. (It hit release candidate a a few days ago, so could be worth checking out)
Good luck with this! :)
I stumbled upon this, 'cause I'd love to see section coloring in Eclipse. Imagine you could simply give some background color to sections within your code. Wouldn't it make it more accessible, especially when you're faded at 4 a.m.? :)
You can mark the code you want to format and selct format with right mouse click in this section. This is a "whitlist" solution, perhaps it helps...