Deprecated: Function set_magic_quotes_runtime() is deprecated in /home/raedan/public_html/textpattern/lib/txplib_db.php on line 14
State of Flow: SubText::projects

SubText

Arguments for Aspect Oriented Programming are also relevant to documentation; documentation crosscuts concerns such as: error checking and handling, synchronization, context-sensitive behavior, performance optimizations, monitoring and logging, debugging support, multi-object protocols, etc.

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.

Why SubText?

There are several advantages:

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:

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:

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

Download

The latest release is com.teaminabox.eclipse.subtext_1.1.0.jar for Eclipse 3.0 and later.

Download the plugin and put the jar into your plugins directory.

Note that you need to restart Eclipse to make the plugin available.

Open the SubText view from Window menu / Show View / Other … / Subtext.

SubText Packs

The beginnings of a set of packs of SubText documents is included in the plugin jar file. To use them, unzip the jar and copy the directory subtextPacks to a project (anywhere in the project).

One of the packs is for JHotDraw which is a good example of a pattern rich, well structured codebase. Download JHotDraw, create a project with the source and all the SubText packs included in the plugin, and browse the source with the SubText view open. SubText will collate documentation and present what is relevant to the class or interface being viewed.

Feedback

This is an experiment to see if there is value in this kind of documentation and whether it should be developed further. We would appreciate your comments and ideas in EPiC’s forums.

Bugs

Please report any bugs in EPiC’s forums