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 example shows you how you can waypoint on your source code with a single tag:

//@tag mytag : This is a comment for my waypoint

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

//@tag mytag : This is a comment for my waypoint

/*
* @tag mytag : This is a comment for my waypoint
*/

/**
* @tag mytag : This is a comment for my waypoint
*/

In the above example, the word "@tag" in the comment indicates that this location (or waypoint) has been tagged as interesting. 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 meta-data. In this example, the only other data that is included is a comment, which is placed after the colon (:) and has the text: "This is a comment for my waypoint".

The format is as follows:

@tag tagname <... more-tag-names> <... meta-data> <: comment text >

Where bold text is required, and text inside <> is optional.

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.

Names that have dots (.) in them can be treated as hierarchical in the views. For example, the tag name tagsea.bug.12 could represent bug number 12 inside the tagsea project, and can be visualized as such inside the Tags View.

Older versions of TagSEA used a different syntax in Java tag names to represent hierarchies. They used a parenthesis syntax. 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 will be 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 is supplied for tag names for when the get too long. 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 comment for my waypoint

or if the author's name contains a space:

//@tag mytag -author="John Doe" : This is a comment for my waypoint

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 comment for my waypoint

January 15, 2007 in US:

//@tag mytag -date="enUS:01/15/07" : This is a comment for my waypoint

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 into a waypoint, 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 as the author, and the current day as the 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.