Stefan Henß

This year I’ve participated in Google Summer of Code by contributing to Eclipse Code Recommenders. The goal of Code Recommenders is to develop various tools which analyze code frameworks and their usage to mine information useful for code documentation and to increase productivity. For example, it compares the user’s code with code from various sources and makes statistical assumptions on which methods should be called next. ExtDoc was created to compile all available information into a handy documentation format integrated in Eclipse.

The Idea

ExtDoc’s approach is to adopt the way Eclipse displays Javadoc, i.e. in a view or when hovering code elements, and to create a framework which allows to contribute any information to similar displays. For instance, Code Recommenders holds statistical information of many kinds for many popular frameworks, but currently lacks a way of displaying all in one place. In order to have information displayed with ExtDoc, each information contributor simply has to implement a “provider” through which he is asked to submit his data for the current user selection. ExtDoc then puts together all providers and allows the user to navigate through the information in multiple spots.

The ExtDoc View

Just like the console or the Javadoc view, the ExtDoc view can be located somewhere around the main editor and reacts to any selection in the editor. In the following, all available providers are depicted as they appear in the ExtDoc view. Additional to the providers’ contents, which are displayed as one scrollable “document” on the right, there is a table on the left indicating all available providers and their status. For example, providers are grayed out if they have nothing available for the current selection or are disabled by the user.

The table also offers the possibility to change the provider order by drag and drop and to disable/re-enable providers perminately. Finally, on top of the table the selection’s location type is displayed (e.g. “field declaration”), since some providers distinct between up to 9 location types. For example, a user might find different information useful when selecting a type in an “extends” statement than in a method body. Therefore the user’s selection of providers is also location-sensitive.

Currently available Providers

The method calls provider offers information on which methods should typically be called for the selected Java element. For example, when selecting SWT’s Text type, it displays the most frequently called methods. When selecting a local variable of type Text, it even takes into consideration which methods have already been called on the variable, which usually influences the probabilities of further method calls.

Sometimes even whole blocks frequently occur in different source codes, e.g. the configuration of reoccurring elements. As a result, not only single method calls but also whole code examples are proposed by ExtDoc. Note: this provider is currently in development and only displays information for a few selected elements.

The usage of a framework typically involves extending provided interfaces, abstract classes or even concrete classes. Not seldom, one is expected to override already implemented methods in order to achieve certain tasks and therefore has to understand the superclass(es) code or rely on a comprehensive documentation. Code Recommenders computes which methods of a class typically are overriden, so-called subclassing directives, which are also displayed in ExtDoc. When selecting an overriden method, ExtDoc even displays which of the superclass’ methods are typically called from the method implementation, e.g. for configuration purposes.

Often framework objects are such comprehensive that the set of overriden methods differs between tasks, i.e. one method might be required to be specified in one scenario, but of no interest at all in the other. Therefore also subclassing patterns are mined, as depicted in the following screenshot.

Finally, the social bookmarks provider allows the users to share web resources. For example, when one experiences difficulties with an API element, he might submit a solution he found one the web as a reference for all other users that might come along this element and have similar issues. In order to filter the most relevant resources, the community is able to rate each link.

Community Feedback

As depicted in all screenshots, all current providers allow users to rate their content through a 5-star system, either the displayed element information as a whole, or single items such as a specific patterns. Furthermore, there is a standard ExtDoc widget which allows commenting the provider content. The following screenshot depicts the expanded comments section underneath the subclassing patterns provider.

The ExtDoc community widgets allow both, communication between the users, e.g. additional information to the displayed data, and feedback to the provider author.

Further ExtDoc Locations

All above screenshots displayed the providers as they appear in the ExtDoc view. However, similar display is also available in two additional locations in which users typically look for documentation. First, the Javadoc pop-up, which is displayed when hovering an element in the editor, is replaced with an ExtDoc pop-up. It contains the same providers “document” as the view does and an additional toolbar underneath, which allows jumping/auto-scrolling to the specific provider. Now, there is no more Javadoc available!? Don’t worry, ExtDoc also contains a provider displaying the traditional Javadoc, as depicted in the very first screenshot :-)

The third location for ExtDoc is the documentation of elements selected in the code assistant pop-up. It offers the same features as the hover pop-up does, as shown below:

Obtaining ExtDoc

Since ExtDoc, among some other Code Recommenders features, is in the testing phase for an upcoming drop, you have to access it either through the head update site or the ExtDoc update site. Both links are given below:

http://www.eclipse.org/recommenders/download/
http://vandyk.st.informatik.tu-darmstadt.de/updates/extdoc/

Feedback on the current state as well as suggestions for further development are much welcome :-)