Package org.eclipse.jdt.internal.formatter.comment

Provides facilities to format comments in Java source code.

See:
Description

Interface Summary

IBorderAttributes	Comment region border attributes.
ICommentAttributes	General comment range attributes.
IHtmlTagDelimiters	Html tag constants.
IJavaDocTagConstants	Javadoc tag constants.

Class Summary

CommentFormatterUtil	Comment formatting utils.
CommentLine	General comment line in a comment region.
CommentRange	Range in a comment region in comment region coordinates.
CommentRegion	Comment region in a source code document.
HTMLEntity2JavaReader	SubstitutionTextReader that will substitute plain text values for html entities encountered in the original text.
Java2HTMLEntityReader	SubstitutionTextReader that will substitute html entities for html symbols encountered in the original text.
JavaDocLine	Javadoc comment line in a comment region.
JavaDocRegion	Javadoc region in a source code document.
MultiCommentLine	Multi-line comment line in a comment region.
MultiCommentRegion	Multi-comment region in a source code document.
SingleCommentLine	Single-line comment line in a comment region.
SubstitutionTextReader	Reads the text contents from a reader and computes for each character a potential substitution.

Package org.eclipse.jdt.internal.formatter.comment Description

Provides facilities to format comments in Java source code.

Package Specification

This package provides interfaces and implementations for three kinds of comment types used in Java source code:

• Javadoc comments
• Multi-line comments
• Single-line comments

Comment Formatting

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 CommentObjectFactory#createRegion(IDocument, TypedPosition, String, Map, StyledText) should be used.

The formatting process is then launch by calling CommentRegion#format(String), 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.

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.

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.
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.

All the objects used during comment formatting should not directly be instantiated, but rather retrieved from the factory CommentObjectFactory. This factory ensures that the right kind of regions and lines are returned for a specific comment type.