<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="Author" content="IBM">
   <title>Package-level Javadoc</title>
</head>
<body>
Provides facilities to format comments in Java source code.
<h2>
Package Specification</h2>
This package provides interfaces and implementations for three kinds of comment types used in 
Java source code:
<ul>
<li>Javadoc comments</li>
<li>Multi-line comments</li>
<li>Single-line comments</li>
</ul>
<h3>
Comment Formatting</h3>
Comment regions form the principle access point to the formatting of comments. To create a comment 
region for a specified comment type, the factory method 
<tt>CommentObjectFactory#createRegion(IDocument, TypedPosition, String, Map, StyledText)</tt> 
should be used.<p>
The formatting process is then launch by calling <tt>CommentRegion#format(String)</tt>, where 
the argument denotes the desired indentation. This method returns a textedit representing the changes that where made during 
the formatting process. The document for which the comment region was created is therefore guaranteed 
to remain unchanged.<p>
Internally, the comment region is first cast into comment lines to form the basis of the following scan step: 
Each comment line is scanned for valid prefixes and tokenized afterwards. This tokenize step yields a stream of 
tokens called comment ranges that are then marked with attributes representing information about the kind of 
token associated with that comment range.<p>
Once the comment ranges have enough attributed information, the comment region wraps the comment ranges at 
the line margin boundary. This is coordinated by a set of rules that can be contributed to a certain type of comment 
region. At this point of time, the comment range stream already represents the formatted comment region. The last 
step therefore is to record the edits and to construct the resulting text edit, which describes all the changes that were 
made to the comment region.
<br>
Note that the changes are not directly applied to the document. Clients are responsible for applying the textedit 
and updating and preserving the document structure.
<p>
All the objects used during comment formatting should not directly be instantiated, but 
rather retrieved from the factory <tt>CommentObjectFactory</tt>. This factory ensures 
that the right kind of regions and lines are returned for a specific comment type.
</body>
</html>