Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/comment/package.html')
-rw-r--r--org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/comment/package.html46
1 files changed, 46 insertions, 0 deletions
diff --git a/org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/comment/package.html b/org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/comment/package.html
new file mode 100644
index 00000000..d2210a7f
--- /dev/null
+++ b/org.eclipse.jdt.core/formatter/org/eclipse/jdt/internal/formatter/comment/package.html
@@ -0,0 +1,46 @@
+<!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>

Back to the top