SubText Plugin
SubText discovers and builds documentation dynamically using a language similar to AspectJ?s pointcuts, enabling designers and developers to present crosscutting documentation where its actively needed during development.
There are several advantages:System level design and architecture decisions are often not visible at the detailed level of writing code. It is easy to become lost in detail, forgetting the big picture. SubText helps developers to keep a system view while coding by presenting relevant documentation based on characteristics of the classes and types being worked on.
SubText can help new developers understand pattern-rich codebases. Generic documentation for well-known design patterns and idioms can be added to any project helping new developers to understand how things work.
Code quality can be improved by providing information about how types should be implemented or extended, and where they should and should not be used.
Developers can continuously refactor and add to SubText documents during a project. Since SubText documents are lightweight, there isn?t a lot of overhead. The result is a set of SubText documents which accurately reflect the design and code of the system being developed.
Future versions could provide a reverse lookup: which types are involved in feature X?
It seemed like a good idea at the time ;)
How Does SubText Work?
A SubText file contains a piece of crosscutting documentation. It must have a ?.subtext?. extension and its form is as follows:
subtext name PointcutExpression; Documentation
name can be any valid Java identifier and Documentation is any text. If the documentation is surrounded by a DIV element then it will be included as HTML. If it is not surrounded by a DIV element it will be wrapped in a PRE element.
The stylesheets, header and footer used by the plugin are in eclipse_install_dir/plugins/com.teaminabox.eclipse.subtext_x.y.z/style.
Pointcut Expressions
The Pointcut Expression is a logical function of type patterns that defines which classes and interfaces a SubText applies to. Patterns can include character, package and subtype wildcards. The pattern syntax is a simplified form of AspectJ?s pointcut syntax.
Pointcut Expression Examples
This expression will match a type if it is a subtype of java.util.Map and if it is declared in packages whose name starts with com.teaminabox.subtext. The unqualified class name of the subtype can be anything.
subtext AllMaps java.util.Map+ && com.teaminabox.subtext..*;
A SubText Map is ...
Any logical expression containing && (and),|| (or), ! (not) with bracketing is supported.
Type Patterns
Types may be matched by:
explicitly using the fully qualified name of the class
the character wildcard ?*? to match zero or more characters except for ?.?
the package wildcard ?..? to match any sequence of characters that start and end with a ?.?, so it can be used to help pick out a selection of packages
the subtype wildcard + will match a type and its subtypes
Type Pattern Examples
The simplest type pattern is a fully qualified class name, which matches precisely the specified type:
subtext Map java.util.Map;
A Map is ...
?*? Character Wildcards can be used as follows:
subtext AllMaps java.util.*Map;
A Map is ...
This expression will match all types whose name ends with Map in the java.util package
?..? Package Wildcards can be used as follows:
subtext SubtextMap com.teaminabox.subtext..*Map;
A SubText Map is ...
This expression will match all types whose unqualified name ends with Map in packages whose name starts with com.teaminabox.subtext.
Subtype Wildcards (+) can be used as follows:
subtext Maps java.util.Map+;
A Map is ...
This expression will match the java.util.Map interface and all implementations and extensions.
subtext Maps ..*Map+;
A Map is ...
This expression will match all types whose unqualified name ends with Map in any package, and its subtypes.
Method Patterns
The components of a method pattern are:
a pattern for the type to which the method belongs
a ?.?
a method name pattern ? can contain the wildcard ?*? to match zero or more characters
a parameter type list or pattern ? the wildcard ?..? means ?any parameters? and may be used in place of the parameter list. Each type in a parameter list is represented by a type pattern.
Method Pattern Examples
The simplest method pattern is a fully qualified class name, which matches precisely the specified type, followed by a full method name with no arguments:
subtext Map java.util.Map.size();
A Map is ...
This expression matches the size() method in java.util.Map
Character Wildcards (*) can be used as follows:
subtext SubtextMapGet com.teaminabox.subtext.Map.get*();
A Map is ...
This expression matches any no-arg method whose name begins with ?get? in the com.teaminabox.subtext.Map type
Specifying parameters explicitly:
subtext MapPut java.util.Map+.put(java.lang.Object, java.lang.Object);
When putting into a map ...
This expression matches any method in subtypes of java.util.Map whose name is ?put? and whose two parameters are of type java.lang.Object
The ?..? parameter wildcard may be used as follows:
subtext MapPut java.util.Map+.put(..);
When putting into a map ...
This expression matches any method in subtypes of java.util.Map whose name is ?put? and which takes any parameters
Type patterns may be used to specify parameters:
subtext MapPut java.util.Map+.put(java.lang.Object+, ..*Object+);
When putting into a map ...
This expression matches any method whose name is ?put? declared in subtypes of java.util.Map and which has two parameters, the first of which must be a subtype of java.lang.Object, and the second must be a subtype of any type whose name ends with ?Object?.
For detail information:
http://www.stateofflow.com/projects/12/subtext