TagSEA 0.6.2

Tags for Software Engineering Activities in Eclipse

Usage

The basic purpose of TagSEA is to allow you to tag software artifacts using TagSEA's waypoint architecture. Exactly how a waypoint is placed on an artifact is dependent on the type of waypoint. For example, Java waypoints are added using special comments in your source code. Resource waypoints are added via context menus in the IDE. The way that a waypoint is added depends on context.

The real power of tags and waypoints, though, isn't in how they are added, it is in how they can be searched and navigated. There are two main views that TagSEA supplies for this operation: the Tags View and the Waypoins View

The Waypoints View

Waypoints 
View

The waypoints view is your point of interaction for all of your waypoints. It is separated into 3 sections:

  1. The Waypoint Table:

    This is a filtered table of the waypoints that can be found by tagsea. Each line represents one waypoint. It has an icon that indicates the kind of waypoint that is on that line, and some descriptive text about the waypoint. The table helps you to navigate to where software artifacts have been tagged. Double-clicking on any waypoint will navigate to the location of that waypoint. How this occurrs is dependant on the type of waypoint. For example, java waypoints will open up a java editor and select the region that the waypoint is on.

    You can filter what is in the view by editing the text box above the table. Entering single words will filter the waypoints based on thier label. The portion of the text that matches the filter is highlighted in the label. You can also filter based on what tags are on the waypoint: simply type something like "@tag-name" to filter out the waypoints that don't have a tag that matches "tag-name". Finally, you can filter based on property values on the waypoint. For example, you can use the fomat "author=John" to see all of the waypoints whose author name *starts with* the word John. You can also use "date<01/01/01" to get all the waypoints that are dated after January 1st, 2001. The format of the date will depend on what locale you are in. Pressing Ctrl-space will give you a list of applicable property names.

  2. The Tags Section:

    This section lists all of the tags that are on the selected waypoint(s). Clicking on a tag name will open it in the Tags Viewer. If only one waypoint is selected, you can use the Edit button to change what tags are on the selected waypoint

  3. The Properties Section:

    If only one waypoint is selected int the waypoint table, you can see a list of properties in this section. Some properties may be editable as well, depending on the type of waypoint. When you edit a property here, the contributed waypoint type has the responsibility to make sure that the platform is updated appropriately. For example, if you change the value of "Author" for a java waypoint, the java source for that waypoint will be automatically updated.

Waypoints always have at least one tag associated with them: the "default" tag. Those tags that have only the default filter will be displayed as grey in the waypoint table. In tagsea, these are often considered to be "unused" waypoints because they haven't been tagged with any "useful" tag names. There is a convenience action to automatically delete all of these waypoints. Be careful though: some of the waypoints may actually be useful. You will be presented with a dialog before the deletion so that you can select specifically which waypoints to delete.

The Tags View

Tags View

The tags view gives you a filtered list of all of the tags available in the platform. You can use the text box to enter words that may match tags that you are interested in. The tags that do not match will be filtered out of the view, and the visible tags will have their matching regions highlighted. The filtering matches any word you enter into the text field.

TagSEA uses a special naming convension to help you organize your tags. The '.' character has a special meaning in TagSEA: it is used to view tags as a hierarchy. When you view your tags as a hierarchy, a number of refactoring actions are available. You can rename your tags by double-clicking on the tag name, or by using the Rename action. You can re-parent tags by dragging them under a new parent. You can delete tags, and you can "generalize" tags. Generalizing tags allows you to remove a particular segment of a tag name without effecting the sub-tree under that segment.

Note that the hierarchical view is enforced by naming convension only. So, if you would like to add an extra level to the sub-tree, you can rename a tag and add an extra '.' to the name. This will refactor all of the tag names under that sub-tree.

When you refactor tags, the effective result is to change the name of the tags in some way. Some waypoint types may not allow you to change the names of their tags (for example, if the waypoint is created on static, read-only data). So, your requested refactoring might not cause a global change. Don't be surprised if you rename a tag, and only some waypoints get moved to that new name. Your old tag might remain behind.

You can also view your tags using their flat, "raw", dot-separated names. When you view them this way, however, only the Rename action is available, and it does not guarantee to keep the hierarchy consistent.


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.