diff options
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.html | 46 |
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> |