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