bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_codeformatter.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   <head>
     <meta name="copyright" content=
     "Copyright (c) IBM Corporation and others 2000, 2017. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
     <meta http-equiv="Content-Type" content=
     "text/html; charset=utf-8" />
     <meta http-equiv="Content-Style-Type" content="text/css" />
     <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1"
     type="text/css" />
     <title>
       Using the code formatter
     </title>
     <link rel="stylesheet" type="text/css" href="../book.css" />

   </head>
   <body>
     <h2>
       Using the code formatter
     </h2>
     <p>
       The JDT API allows other plug-ins to use the default
       <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
       code formatter</a></b> to format source code. The two methods
       to consider are:
     </p>

     <ul>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/ToolFactory.html#createCodeFormatter(java.util.Map)">
         ToolFactory.createCodeFormatter(Map)</a></b>
       </li>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/ToolFactory.html#createCodeFormatter(java.util.Map,%20int)">
         ToolFactory.createCodeFormatter(Map, int)</a></b>

       </li>
     </ul>
     <p>
       Note: The <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
       CodeFormatter</a></b> class is not intended to be subclassed
       by clients.
     </p>
     <h3>
       Getting a code formatter instance
     </h3>

     <p>
       The factory methods on <b><a href=
       "../reference/api/org/eclipse/jdt/core/ToolFactory.html">ToolFactory</a></b>
       can be invoked to create a new instance of the default code
       formatter. Before invoking one of those, you need to define a
       map that contains the code formatter options. In order to
       create such a map, you can use the methods defined in the
       class <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">
       DefaultCodeFormatterConstants</a></b> like <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#getEclipseDefaultSettings()">
       DefaultCodeFormatterConstants.getEclipseDefaultSettings()</a></b>

     </p>
     <p>
       NOTE: These predefined maps contain only the code formatter
       specific options. In order to invoke the code formatter, you
       also need to specify what kind of source the code formatter
       will format. In order to do so, specify the three options:
     </p>
     <ul>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_CODEGEN_TARGET_PLATFORM">
         JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM</a></b>
       </li>

       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_SOURCE">
         JavaCore.COMPILER_SOURCE</a></b>
       </li>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_COMPLIANCE">
         JavaCore.COMPILER_COMPLIANCE</a></b>
       </li>

     </ul>
     <p>
       The possible values of these options are given by the
       constants:
     </p>
     <ul>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_1">
         JavaCore.VERSION_1_1</a></b>
       </li>

       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_2">
         JavaCore.VERSION_1_2</a></b>
       </li>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_3">
         JavaCore.VERSION_1_3</a></b>
       </li>

       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_4">
         JavaCore.VERSION_1_4</a></b>
       </li>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_5">
         JavaCore.VERSION_1_5</a></b>
       </li>

       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_6">
         JavaCore.VERSION_1_6</a></b>
       </li>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_7">
         JavaCore.VERSION_1_7</a></b>
       </li>
 	 <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_8">
         JavaCore.VERSION_1_8</a></b>
       </li>
 	 <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_8">
         JavaCore.VERSION_9</a></b>
       </li>
     </ul>
     <p>
       If you want to modify the default maps, it is recommended
       that you use the methods defined on <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">
       DefaultCodeFormatterConstants</a></b> to create the values of
       the corresponding options. This is especially true for the
       options relative to code wrapping.
     </p>
     <h3>
       Invoking the code formatter
     </h3>

     <p>
       Use the newly created code formatter to format code snippets.
       The default code formatter allows you to format different
       kind of code snippets.<br />
       These kinds are specified in the documentation of the
       <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20int,%20int,%20int,%20java.lang.String)">
       format</a></b> method. The returned value of this method is a
       text edit. This text edit then needs to be applied to an
       <b><a href=
       "../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/text/IDocument.html">
       IDocument</a></b> instance in order to get the formatted
       result.
     </p>

     <h4>
       Example
     </h4>
     <pre class="color1">
 	// take default Eclipse formatting options
 	Map options = DefaultCodeFormatterConstants.getEclipseDefaultSettings();

 	// initialize the compiler settings to be able to format 1.5 code
 	options.put(JavaCore.COMPILER_COMPLIANCE, JavaCore.VERSION_1_5);
 	options.put(JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM, JavaCore.VERSION_1_5);
 	options.put(JavaCore.COMPILER_SOURCE, JavaCore.VERSION_1_5);

 	// change the option to wrap each enum constant on a new line
 	options.put(
 		DefaultCodeFormatterConstants.FORMATTER_ALIGNMENT_FOR_ENUM_CONSTANTS,
 		DefaultCodeFormatterConstants.createAlignmentValue(
 		true,
 		DefaultCodeFormatterConstants.WRAP_ONE_PER_LINE,
 		DefaultCodeFormatterConstants.INDENT_ON_COLUMN));

 	// instantiate the default code formatter with the given options
 	final CodeFormatter codeFormatter = ToolFactory.createCodeFormatter(options);

 	// retrieve the source to format
 	String source = null;
 	try {
 		source = ...; // retrieve the source
 	} catch (IOException e) {
 		System.err.println("Could not retrieve the source"); //$NON-NLS-1$
 		e.printStackTrace();
 		return;
 	}
 	final TextEdit edit = codeFormatter.format(
 		CodeFormatter.K_COMPILATION_UNIT, // format a compilation unit
 		source, // source to format
 		0, // starting position
 		source.length(), // length
 		0, // initial indentation
 		System.getProperty("line.separator") // line separator
 	);

 	IDocument document = new Document(source);
 	try {
 		edit.apply(document);
 	} catch (MalformedTreeException e) {
 		e.printStackTrace();
 	} catch (BadLocationException e) {
 		e.printStackTrace();
 	}

 	// display the formatted string on the System out
 	System.out.println(document.get());
 </pre>
     <p>
       On this example,
     </p>
     <pre class="color1">
 public enum X { A,B,C,D,E,F}
 </pre>
     <p>
       the result would be:
     </p>
     <pre class="color1">
 public enum X {
 	A,
 	B,
 	C,
 	D,
 	E,
 	F
 }
 </pre>
     <h3>
       Formatting a set of regions
     </h3>
     <p>

       The default <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
       code formatter</a></b> allows to format a set of regions of a
       given source file.<br />
       This can be achieved by calling the <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20org.eclipse.jface.text.IRegion[],%20int,%20java.lang.String)">
       format(int, String, IRegion[], int, String)</a></b> method of
       the code formatter, with a given <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_UNKNOWN">
       source kind</a></b> and an array of <b><a href=
       "../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/text/IRegion.html">

       regions</a></b>.
     </p>
     <ul>
       <li>Each of the region to format must be within source range
       and should not overlap with another region.
       </li>
       <li>The array of regions to format must contain at least one
       region. Regions should be sorted by their offsets, smaller
       offset first.
       </li>
     </ul>
     <h3>
       Comment Formatter API
     </h3>

     <p>
       The default <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
       code formatter</a></b> API offers the possibility to format
       comments during the processing of the code snippet.<br />
       This can be achieved by combining the appropriate flag
       <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#F_INCLUDE_COMMENTS">
       F_INCLUDE_COMMENTS</a></b> with <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_COMPILATION_UNIT">

       K_COMPILATION_UNIT</a></b> and <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_UNKNOWN">
       K_UNKNOWN</a></b> flags.<br />
       <br />
       This flag is effective only if the corresponding formatting
       option was enabled when calling <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20int,%20int,%20int,%20java.lang.String)">
       format(int, String, int, int, int, String)</a></b> or
       <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20org.eclipse.jface.text.IRegion[],%20int,%20java.lang.String)">

       format(int, String, IRegion[], int, String)</a></b> methods:
     </p>
     <ul>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#FORMATTER_COMMENT_FORMAT_JAVADOC_COMMENT">
         FORMATTER_COMMENT_FORMAT_JAVADOC_COMMENT</a></b> which
         controls the formatting of javadoc comments
       </li>
       <li>

         <b><a href=
         "../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#FORMATTER_COMMENT_FORMAT_BLOCK_COMMENT">
         FORMATTER_COMMENT_FORMAT_BLOCK_COMMENT</a></b> which
         controls the formatting of multiple lines comments
       </li>
       <li>
         <b><a href=
         "../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#FORMATTER_COMMENT_FORMAT_LINE_COMMENT">
         FORMATTER_COMMENT_FORMAT_LINE_COMMENT</a></b> which
         controls the formatting of single line comments
       </li>
     </ul>

     <h3>
       Comment formatter options
     </h3>
     <p>
       Various formatting options are available in order to format
       comments:
     </p>
     <ul>
       <li>General options to enable or disable the formatting of
       specific comments (javadoc, multi or single line comments),
       set maximum line width for comments.
       </li>
       <li>javadoc comments options to enable the formatting of code
       snippets or HTML sections inside javadoc comments, indent tag
       descriptions, etc.
       </li>

       <li>block comments option to keep or remove blanks lines
       within such comment
       </li>
     </ul>
     <p>
       For detailed information about these settings, refer to the
       <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">
       DefaultCodeFormatterConstants</a></b>
     </p>
     <h3>

       Formatting comments with the stand-alone formatter
     </h3>
     <p>
       The default <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
       code formatter</a></b> can be used to format comments
       (javadoc, multi or single line). In this case, the source
       passed to the <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20int,%20int,%20int,%20java.lang.String)">
       format method</a></b> should only contain a specific kind of
       comments, and corresponding kind <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_JAVA_DOC">

       K_JAVA_DOC</a></b>, <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_MULTI_LINE_COMMENT">
       K_MULTI_LINE_COMMENT</a></b> or <b><a href=
       "../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_SINGLE_LINE_COMMENT">
       K_SINGLE_LINE_COMMENT</a></b> should be used.
     </p>
     <ul>
       <li>

         <h4>
           Formatting javadoc comments
         </h4>
         <p>
           The following unformatted javadoc:
         </p>
         <pre class="color1">
   /**
  * This is just a simple example to show how javadoc comments can     be formatted .
  * @param str The input string
    * @return      The resulting   string
    */
 </pre>
         <p>

           should be formatted as follows:
         </p>
         <pre class="color1">
 /**
  * This is just a simple example to show how javadoc comments can be formatted .
  *
  * @param str
  *            The input string
  * @return The resulting string
  */
 </pre>
         <p>
           using command:
         </p>
 <pre class="color1">
 	(...)
 	final TextEdit edit = codeFormatter.format(
 		<b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_JAVA_DOC">CodeFormatter.K_JAVA_DOC</a></b>, // specify the kind: javadoc
 		source, // source to format (as per the above example)
 		0, // starting position
 		source.length(), // length
 		0, // initial indentation
 		System.getProperty("line.separator") // line separator
 	);
 	(...)

 </pre>
       </li>
       <li>
         <h4>
           Formatting multi-line comments
         </h4>
         <p>
           The following unformatted multi-line comment:
         </p>
         <pre class="color1">

 /*
   * This is just an example of multi- line comment intended to demonstrate the default code formatter ability to format multi-line comments .
   *
   *   These possibilities include: Formatting of javadoc     comments,
   *     formatting of multi-line comments
  */
 </pre>
         <p>
           should be formatted as follows:
         </p>
         <pre class="color1">
 /*
  * This is just an example of multi- line comment intended to demonstrate
  * the default code formatter ability to format multi-line comments .
  *
  * These possibilities include: Formatting of javadoc comments, formatting
  * of multi-line comments
  */
 </pre>
         <p>
           using command:
         </p>
         <pre class="color1">
 	(...)
 	final TextEdit edit = codeFormatter.format(
 		<b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_MULTI_LINE_COMMENT">CodeFormatter.K_MULTI_LINE_COMMENT</a></b>, // specify the kind: multi-line comments
 		source, // source to format (as per the above example)
 		0, // starting position
 		source.length(), // length
 		0, // initial indentation
 		System.getProperty("line.separator") // line separator
 	);
 	(...)
 </pre>
       </li>
       <li>
         <h4>
           Formatting single line comments
         </h4>
         <p>
           The following unformatted single line comments:
         </p>

         <pre class="color1">
 // This is a long comment that should be split in multiple line comments in case the line comment formatting is enabled
 </pre>
         <p>
           should be formatted as follows:
         </p>
         <pre class="color1">
 // This is a long comment that should be split in multiple line comments in
 // case the line comment formatting is enabled
 </pre>
         <p>
           using command:
         </p>

         <pre class="color1">
 	(...)
 	final TextEdit edit = codeFormatter.format(
 		<b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_SINGLE_LINE_COMMENT">CodeFormatter.K_SINGLE_LINE_COMMENT</a></b>,  // specify the kind: single-line comments
 		source, // source to format (as per the above example)
 		0, // starting position
 		source.length(), // length
 		0, // initial indentation
 		System.getProperty("line.separator") // line separator
 	);
 	(...)
 </pre>
       </li>
     </ul>
   </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<meta name="copyright" content=
	"Copyright (c) IBM Corporation and others 2000, 2017. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
	<meta http-equiv="Content-Type" content=
	"text/html; charset=utf-8" />
	<meta http-equiv="Content-Style-Type" content="text/css" />
	<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1"
	type="text/css" />
	<title>
	Using the code formatter
	</title>
	<link rel="stylesheet" type="text/css" href="../book.css" />

	</head>
	<body>
	<h2>
	Using the code formatter
	</h2>
	<p>
	The JDT API allows other plug-ins to use the default
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
	code formatter</a></b> to format source code. The two methods
	to consider are:
	</p>

	<ul>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/ToolFactory.html#createCodeFormatter(java.util.Map)">
	ToolFactory.createCodeFormatter(Map)</a></b>
	</li>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/ToolFactory.html#createCodeFormatter(java.util.Map,%20int)">
	ToolFactory.createCodeFormatter(Map, int)</a></b>

	</li>
	</ul>
	<p>
	Note: The <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
	CodeFormatter</a></b> class is not intended to be subclassed
	by clients.
	</p>
	<h3>
	Getting a code formatter instance
	</h3>

	<p>
	The factory methods on <b><a href=
	"../reference/api/org/eclipse/jdt/core/ToolFactory.html">ToolFactory</a></b>
	can be invoked to create a new instance of the default code
	formatter. Before invoking one of those, you need to define a
	map that contains the code formatter options. In order to
	create such a map, you can use the methods defined in the
	class <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">
	DefaultCodeFormatterConstants</a></b> like <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#getEclipseDefaultSettings()">
	DefaultCodeFormatterConstants.getEclipseDefaultSettings()</a></b>

	</p>
	<p>
	NOTE: These predefined maps contain only the code formatter
	specific options. In order to invoke the code formatter, you
	also need to specify what kind of source the code formatter
	will format. In order to do so, specify the three options:
	</p>
	<ul>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_CODEGEN_TARGET_PLATFORM">
	JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM</a></b>
	</li>

	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_SOURCE">
	JavaCore.COMPILER_SOURCE</a></b>
	</li>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_COMPLIANCE">
	JavaCore.COMPILER_COMPLIANCE</a></b>
	</li>

	</ul>
	<p>
	The possible values of these options are given by the
	constants:
	</p>
	<ul>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_1">
	JavaCore.VERSION_1_1</a></b>
	</li>

	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_2">
	JavaCore.VERSION_1_2</a></b>
	</li>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_3">
	JavaCore.VERSION_1_3</a></b>
	</li>

	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_4">
	JavaCore.VERSION_1_4</a></b>
	</li>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_5">
	JavaCore.VERSION_1_5</a></b>
	</li>

	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_6">
	JavaCore.VERSION_1_6</a></b>
	</li>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_7">
	JavaCore.VERSION_1_7</a></b>
	</li>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_8">
	JavaCore.VERSION_1_8</a></b>
	</li>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_8">
	JavaCore.VERSION_9</a></b>
	</li>
	</ul>
	<p>
	If you want to modify the default maps, it is recommended
	that you use the methods defined on <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">
	DefaultCodeFormatterConstants</a></b> to create the values of
	the corresponding options. This is especially true for the
	options relative to code wrapping.
	</p>
	<h3>
	Invoking the code formatter
	</h3>

	<p>
	Use the newly created code formatter to format code snippets.
	The default code formatter allows you to format different
	kind of code snippets.<br />
	These kinds are specified in the documentation of the
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20int,%20int,%20int,%20java.lang.String)">
	format</a></b> method. The returned value of this method is a
	text edit. This text edit then needs to be applied to an
	<b><a href=
	"../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/text/IDocument.html">
	IDocument</a></b> instance in order to get the formatted
	result.
	</p>

	<h4>
	Example
	</h4>
	<pre class="color1">
	// take default Eclipse formatting options
	Map options = DefaultCodeFormatterConstants.getEclipseDefaultSettings();

	// initialize the compiler settings to be able to format 1.5 code
	options.put(JavaCore.COMPILER_COMPLIANCE, JavaCore.VERSION_1_5);
	options.put(JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM, JavaCore.VERSION_1_5);
	options.put(JavaCore.COMPILER_SOURCE, JavaCore.VERSION_1_5);

	// change the option to wrap each enum constant on a new line
	options.put(
	DefaultCodeFormatterConstants.FORMATTER_ALIGNMENT_FOR_ENUM_CONSTANTS,
	DefaultCodeFormatterConstants.createAlignmentValue(
	true,
	DefaultCodeFormatterConstants.WRAP_ONE_PER_LINE,
	DefaultCodeFormatterConstants.INDENT_ON_COLUMN));

	// instantiate the default code formatter with the given options
	final CodeFormatter codeFormatter = ToolFactory.createCodeFormatter(options);

	// retrieve the source to format
	String source = null;
	try {
	source = ...; // retrieve the source
	} catch (IOException e) {
	System.err.println("Could not retrieve the source"); //$NON-NLS-1$
	e.printStackTrace();
	return;
	}
	final TextEdit edit = codeFormatter.format(
	CodeFormatter.K_COMPILATION_UNIT, // format a compilation unit
	source, // source to format
	0, // starting position
	source.length(), // length
	0, // initial indentation
	System.getProperty("line.separator") // line separator
	);

	IDocument document = new Document(source);
	try {
	edit.apply(document);
	} catch (MalformedTreeException e) {
	e.printStackTrace();
	} catch (BadLocationException e) {
	e.printStackTrace();
	}

	// display the formatted string on the System out
	System.out.println(document.get());
	</pre>
	<p>
	On this example,
	</p>
	<pre class="color1">
	public enum X { A,B,C,D,E,F}
	</pre>
	<p>
	the result would be:
	</p>
	<pre class="color1">
	public enum X {
	A,
	B,
	C,
	D,
	E,
	F
	}
	</pre>
	<h3>
	Formatting a set of regions
	</h3>
	<p>

	The default <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
	code formatter</a></b> allows to format a set of regions of a
	given source file.<br />
	This can be achieved by calling the <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20org.eclipse.jface.text.IRegion[],%20int,%20java.lang.String)">
	format(int, String, IRegion[], int, String)</a></b> method of
	the code formatter, with a given <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_UNKNOWN">
	source kind</a></b> and an array of <b><a href=
	"../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/text/IRegion.html">

	regions</a></b>.
	</p>
	<ul>
	<li>Each of the region to format must be within source range
	and should not overlap with another region.
	</li>
	<li>The array of regions to format must contain at least one
	region. Regions should be sorted by their offsets, smaller
	offset first.
	</li>
	</ul>
	<h3>
	Comment Formatter API
	</h3>

	<p>
	The default <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
	code formatter</a></b> API offers the possibility to format
	comments during the processing of the code snippet.<br />
	This can be achieved by combining the appropriate flag
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#F_INCLUDE_COMMENTS">
	F_INCLUDE_COMMENTS</a></b> with <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_COMPILATION_UNIT">

	K_COMPILATION_UNIT</a></b> and <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_UNKNOWN">
	K_UNKNOWN</a></b> flags.<br />
	<br />
	This flag is effective only if the corresponding formatting
	option was enabled when calling <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20int,%20int,%20int,%20java.lang.String)">
	format(int, String, int, int, int, String)</a></b> or
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20org.eclipse.jface.text.IRegion[],%20int,%20java.lang.String)">

	format(int, String, IRegion[], int, String)</a></b> methods:
	</p>
	<ul>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#FORMATTER_COMMENT_FORMAT_JAVADOC_COMMENT">
	FORMATTER_COMMENT_FORMAT_JAVADOC_COMMENT</a></b> which
	controls the formatting of javadoc comments
	</li>
	<li>

	<b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#FORMATTER_COMMENT_FORMAT_BLOCK_COMMENT">
	FORMATTER_COMMENT_FORMAT_BLOCK_COMMENT</a></b> which
	controls the formatting of multiple lines comments
	</li>
	<li>
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#FORMATTER_COMMENT_FORMAT_LINE_COMMENT">
	FORMATTER_COMMENT_FORMAT_LINE_COMMENT</a></b> which
	controls the formatting of single line comments
	</li>
	</ul>

	<h3>
	Comment formatter options
	</h3>
	<p>
	Various formatting options are available in order to format
	comments:
	</p>
	<ul>
	<li>General options to enable or disable the formatting of
	specific comments (javadoc, multi or single line comments),
	set maximum line width for comments.
	</li>
	<li>javadoc comments options to enable the formatting of code
	snippets or HTML sections inside javadoc comments, indent tag
	descriptions, etc.
	</li>

	<li>block comments option to keep or remove blanks lines
	within such comment
	</li>
	</ul>
	<p>
	For detailed information about these settings, refer to the
	<b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">
	DefaultCodeFormatterConstants</a></b>
	</p>
	<h3>

	Formatting comments with the stand-alone formatter
	</h3>
	<p>
	The default <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">
	code formatter</a></b> can be used to format comments
	(javadoc, multi or single line). In this case, the source
	passed to the <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int,%20java.lang.String,%20int,%20int,%20int,%20java.lang.String)">
	format method</a></b> should only contain a specific kind of
	comments, and corresponding kind <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_JAVA_DOC">

	K_JAVA_DOC</a></b>, <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_MULTI_LINE_COMMENT">
	K_MULTI_LINE_COMMENT</a></b> or <b><a href=
	"../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_SINGLE_LINE_COMMENT">
	K_SINGLE_LINE_COMMENT</a></b> should be used.
	</p>
	<ul>
	<li>

	<h4>
	Formatting javadoc comments
	</h4>
	<p>
	The following unformatted javadoc:
	</p>
	<pre class="color1">
	/**
	* This is just a simple example to show how javadoc comments can be formatted .
	* @param str The input string
	* @return The resulting string
	*/
	</pre>
	<p>

	should be formatted as follows:
	</p>
	<pre class="color1">
	/**
	* This is just a simple example to show how javadoc comments can be formatted .
	*
	* @param str
	* The input string
	* @return The resulting string
	*/
	</pre>
	<p>
	using command:
	</p>
	<pre class="color1">
	(...)
	final TextEdit edit = codeFormatter.format(
	<b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_JAVA_DOC">CodeFormatter.K_JAVA_DOC</a></b>, // specify the kind: javadoc
	source, // source to format (as per the above example)
	0, // starting position
	source.length(), // length
	0, // initial indentation
	System.getProperty("line.separator") // line separator
	);
	(...)

	</pre>
	</li>
	<li>
	<h4>
	Formatting multi-line comments
	</h4>
	<p>
	The following unformatted multi-line comment:
	</p>
	<pre class="color1">

	/*
	* This is just an example of multi- line comment intended to demonstrate the default code formatter ability to format multi-line comments .
	*
	* These possibilities include: Formatting of javadoc comments,
	* formatting of multi-line comments
	*/
	</pre>
	<p>
	should be formatted as follows:
	</p>
	<pre class="color1">
	/*
	* This is just an example of multi- line comment intended to demonstrate
	* the default code formatter ability to format multi-line comments .
	*
	* These possibilities include: Formatting of javadoc comments, formatting
	* of multi-line comments
	*/
	</pre>
	<p>
	using command:
	</p>
	<pre class="color1">
	(...)
	final TextEdit edit = codeFormatter.format(
	<b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_MULTI_LINE_COMMENT">CodeFormatter.K_MULTI_LINE_COMMENT</a></b>, // specify the kind: multi-line comments
	source, // source to format (as per the above example)
	0, // starting position
	source.length(), // length
	0, // initial indentation
	System.getProperty("line.separator") // line separator
	);
	(...)
	</pre>
	</li>
	<li>
	<h4>
	Formatting single line comments
	</h4>
	<p>
	The following unformatted single line comments:
	</p>

	<pre class="color1">
	// This is a long comment that should be split in multiple line comments in case the line comment formatting is enabled
	</pre>
	<p>
	should be formatted as follows:
	</p>
	<pre class="color1">
	// This is a long comment that should be split in multiple line comments in
	// case the line comment formatting is enabled
	</pre>
	<p>
	using command:
	</p>

	<pre class="color1">
	(...)
	final TextEdit edit = codeFormatter.format(
	<b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#K_SINGLE_LINE_COMMENT">CodeFormatter.K_SINGLE_LINE_COMMENT</a></b>, // specify the kind: single-line comments
	source, // source to format (as per the above example)
	0, // starting position
	source.length(), // length
	0, // initial indentation
	System.getProperty("line.separator") // line separator
	);
	(...)
	</pre>
	</li>
	</ul>
	</body>
	</html>