Tagging directly in the source code (Java, C and C++ code)

TagSEA allows you to tag locations of interest directly in your source code as you type. The following shows an example using a single tag:

//@tag mytag : This is a message.

Tagged locations can appear within any valid Java comment, but only exist on a single line. These are all equivalent:

//@tag mytag : This is a message.

/*
* @tag mytag : This is a message.
*/

/**
* @tag mytag : This is a message.
*/

In the above example, the word "@tag" in the comment indicates that this location (or waypoint) has been tagged. The words immediately following this indicator are the tag names, or keywords that you can use to return to this location later. The waypoint includes all of the defining features of that place, such as the file that contains the tags, the location in that file (both implicitly known by where the text has been typed), as well as other metadata. In this example, the only other data that is included is a message, which is placed after the colon (:).

The syntax is as follows:

@tag tagnames metadata : message

Where bold text is required.

Tag Names

Tag names are descriptive keywords for a location. They can contain any characters except white-space (spaces, tabs, or new-lines), or colons.

Hierarchical tags
Names that have dots (.) in them are treated as hierarchical tags in the TagSEA view. For example, the tag tagsea.bug.12 could represent bug number 12 inside the tagsea project.

Older syntax
Original versions of TagSEA used a parenthesis syntax in Java tag names to represent hierarchies. So, the above tag name would be represented as tagsea(bug(12)). For backward-compatablity, this syntax is still allowed inside the Java waypointing plugin, but it is translated into the standard dot-syntax within the platform. However, since both parentheses and dots have the same interpretation in the Java waypointing plugin, it is illegal to have a tag name that contains both dots and parentheses.

Content-assist
Content-assist is supplied for tag names. Press Ctrl-space to get a list of known tag names.

Author metadata

You can add metadata to identify the author of a tagged location.

For example:

//@tag mytag -author=John : This is a message.

or if the author's name contains a space:

//@tag mytag -author="John Doe" : This is a message.

Since the colon character has a special function, attribute values that have colons in them must also be placed in quotes. Attribute values cannot have quotes as part of the value.

Date metadata

You can also specify a date. TagSEA supports date formats for different regions of the world. The format for a locale-specific date is:

-date="languageCOUNTRY:Short-Date"

Where language is the two-letter ISO language code, COUNTRY is the two-letter ISO country code, and Short-Date is the short-date format as defined by the Java standard.

Examples:

January 15, 2007 in Canada:

//@tag mytag -date="enCA:15/01/07" : This is a message.

January 15, 2007 in US:

//@tag mytag -date="enUS:01/15/07" : This is a message.

If no locale is specified, the default locale is used.

Content assist & quick fixes

All of this can be a lot of stuff to type, so content-assists (Ctrl-space) and quick-fixes (Ctrl-1) are contributed to make things smoother. These two features will automatically enter the current user and date within your tag comment.

Tags for Software Engineering Activities in Eclipse (TagSEA)
is a research collaboration between the University of Victoria's Computer Human Interaction & Software Engineering Lab and the IBM Watson Research Centre.