Chapter 1. User Manual

Table of Contents

What is Code Recommenders?
Recommenders' Code Completion Engines
Intelligent Call Completion
Intelligent Code Templates (single-object, no-order)
Intelligent Overrides Completion
Subwords Completion
Chain Completion
The Extended Documentation Platform
Subclassing Directives Provider
Self-calls Directives Provider
Example Code Snippets Provider
Calls Recommendation Provider
Snipmatch
Local Code-Search
The Model Repository

What is Code Recommenders?

Code Recommenders supports developers learning new APIs by providing tools which learn correct API usages or valuable patterns by analyzing example code and re-integrates this knowledge back into your IDE.

Put differently, it helps your team to cut down development costs when dealing with new APIs by means of intelligent code completion, extended documentation, smart bug detection systems and others - all powered by the knowledge of the programming masses.

Code Recommenders is a set of IDE extensions for the Java programming language. In version 1.0, recommenders consists of two large component groups:

  • 5 Intelligent Code Completion Engines,

  • 4 Extended Documentation Providers,

which will be introduced in detail below.

Recommenders' Code Completion Engines

Intelligent Call Completion

The intelligent call completion engine probably illustrates the idea of Code Recommenders best. When dealing with Framework APIs, developers frequently have to deal with complex APIs. For illustration, consider the public API of javax.swing.JButton which consists of 381 public methods. A huge API of which a developer typically only has to know a small subset. The remaining, say, 360 methods bloat the API (from a API user's viewpoint) and thus unnecessarily increase the complexity of learning and using this API.

All potential completions for JButton

This is where Code Recommenders intelligent call completion comes in. It assists developers by recommending him only those methods that are actually relevant for his task at hand. For instance, given that a developer just created a text widget makes it obvious for Code Recommenders which methods a developer wants to use next - even if the developer doesn't know it by himself:

Recommenders' Intelligent Completion on SWT Text after calling new Text()

At the time of writing this section (1.0.0.rc2), Code Recommenders partially supports the Java Standard Library, namely the main packages under java.* and some packages under javax.* . As the recommendation models are generated from the Eclipse Juno Release Train code base only, packages like java.awt or javax.swing are not supported as no data was available at generation time. For a detailed list of which libraries or packages are supported, check the reports section on the Code Recommenders home page.

Configuration

Code Recommenders intelligent completion engines can be enabled and disabled in its preference page:

Call Completion Preference Page

Furthermore, how many proposals Recommenders computes as well as some recommendation model information can be configured here too.

Intelligent Code Templates (single-object, no-order)

Code templates are helpful when code is needed to iterate over an array of objects or when creating a getter for a property of a class. But code templates really shine when developers have to use APIs they are not very familiar with. Then, code templates serve as additional documentation that quickly shows how an API can be used and save developers lot of time otherwise needed for reading API documentation.

Eclipse maintains more than 70 of such Java code templates - ranging from simple for loops up to complex API usage patterns like creating an SWT Button or Composite . Unfortunately, developing templates for API usage patterns is extremely costly and tedious - and in consequence only few templates for few APIs exist.

This is where Code Recommenders comes in again. In the previous section we showed how to recommend single methods to invoke on an object. Templates completion takes this to the next level by recommending not only single methods but complete sets of methods:

Intelligent Template Completion on JDT ASTParser

As you probably have noticed in the example above, Recommenders' templates completion can be applied on existing variables to complete existing usages but also works on type names as the example below shows:

Intelligent Template Completion on JFace TableViewer

The final result after applying the template looks as follows:

Resulting code snippet for JFace TableViewer

Warning

The generated template proposals do not reflect method execution ordering constraints, i.e., the order of the proposed method may have to be changed manually after insertion.

Configuration

Template Completion yet has no configurable options. Note that Templates Completion can not be run on the default content assist. As soon as it detects it was configured for default content assist it immediately deactivates itself. This decision was made because of performance reasons. Computing likely code snippets is a computation-intensive task developers should trigger explicitly.

Intelligent Overrides Completion

Similar to recommending method calls, one can also recommend which methods a developer should typically override. This is what Recommenders intelligent overrides completion does. We'll discuss class extension patterns in more detail in the extended documentatiton chapter below.

Recommenders' Intelligent Overrides Completion on JFace Dialog

Configuration

Intelligent Overrides Completion yet has no configurable options. It is enabled and disabled together with Recommenders Call Completion, i.e., deactivating Code Recommenders content assist category in JDT, will automatically disable Intelligent Overrides Completion.

Subwords Completion

You probably know JDT's CamelCaseCompletion . This is a nice engine but requires you to remember exactly the uppercase letters of the completion proposal you want to insert. Subwords makes this more convenient. The idea is simple enough - you should not have to type a name from the beginning to find a match in the content assist popup. It helps when a developer doesn not know if one has to 'find' - or - 'get' an element.

Recommenders' Subwords Completion on JDT's CompilationUnit

The feature is sophisticated enough to understand a rough shorthand e.g. dclr for declaration .

Recommenders' Subwords Completion Completion on JDT's AST

It is also sophisticated enough to understand that a method or type name in Java is composed of several words e.g. 'ty + dclr' finds all 'type' + 'declarations'.

Recommenders' Subwords Completion Completion on JDT's AST

Note

Subwords does not fall into the group of intelligent completion engines, i.e., it does not need any training data and thus works with any framework or API out of the box.

This section is based on the work of Deepak Azad, JDT Committer, source: http://blog.deepakazad.com/2012/05/

Configuration

Note that Subwords can not be used together with JDT's or Mylyn's content assist engines. It actually disables itself immediately as soon as it detects that either Mylyn or JDT is enabled on the default content assist list. To use Subwords on the default (first) content assist list, you have to explicitly disable JDT and Mylyn and enable Subwords via Preferences » Java » Editor » Content Assist » Advanced » Default Content Assist

Subwords offers a shortcut for doing this enable and disablement automatically. Visit the Subwords preference page to use that shortcut.

Subwords Preference Page: Configuration Shortcut

Chain Completion

Recommenders' Chain Completion on IStatusLineManager in a ViewPart

Configuration

Note

Note that Recommenders Chain completion cannot be used on the default (first) content assist list. It actually disables itself immediately as soon as it detects that it was configured for the default list. The main reason for this is, that chain completion is essentially an exhaustive search that consumes a lot of CPU time, and thus, should only run when explicitly requested.

Chain completion allows its search to be configurations for specia situations. To change chain completion's defaults visit its preference page under Preferences » Code Recommenders » Chain :

Chain Completion Preference Page

Maximum Number of Chains:

Limits the number of call chains found to max. Has the effect that search is immediately terminated after max number of chains have been found. Change this parameter to gain performance improvements.

Maximum Chains Depth:

Limits how many levels in the API call graph chain completion traverses to find matching call chains. Set this to lowerer levels (e.g. three) if you only want chain completion to find chains of the maximal lenght of three.

Search Timeout (sec):

API graph traversal uses a time limit when searching for chains. Modify this value if chain completion does not find the propsoals due to time limits. Please note that JDT has a built in performance measure and brings up a warning if a content assist engine needs longer thatn 4.5 seconds.

Types Ignore List:

Some type result in far too many proposal, like java.ang.String . Such types can be explicitly excluded from search by adding them to the ignore list.

The Extended Documentation Platform

Writing documentation is one of those tasks programmers are typically not very keen about. It is time-consuming, tedious, and has almost no immediate rewards. Consequently, documentation is (too) often incomplete (or even worse) completely outdated.

But good and comprehensive documentation is crucial for the success of a library or framework. Tools exist, that generate documentation from source code (i.e., extracting obvious information from code and generating more or less helpful javadoc comments). Such approaches seem valuable at first, but finally this kind of documentation only pleases our manager since it improves on the source code to documentation ratio; from a developer's point of view this documentation is rather useless.

However, there are many other resources out there that offer valuable information about an API. Stackoverflow for instance is an abundant source of information providing valuable tips on how to use a certain API or deal with errors. Code-search engines offer code snippets showing how to use an API in action etc. Many more resources exist. The Extended Documentation Platform is solely developed to serve the purpose to aggregate this the wide range of information sources available on the web into a single view in Eclipse.

The figure below shows the Ext ended Doc umentation View ( Extdoc View for short). It basically consists of two parts: a provider overview panel on the left and a content area on the right in which every provider presents its information is has for a given selection in the workspace or active JavaEditor:

Subclassing Directives Provider

Self-calls Directives Provider

Example Code Snippets Provider

Calls Recommendation Provider

Snipmatch

Snipmatch is currently moving in an not ready for 1.0.0.

Local Code-Search

Recommenders' local code-search engine is also not ready for 1.0.0., and thus, will not be part of the Juno release. However, first prototype are available and can be installed from the Recommenders' lab channel.

The Model Repository

Code Recommenders uses precomputed recommendation models to make its proposals. These models are hosted under http://download.eclipse.org/recommenders/models/«release» and downloaded automatically on first access. Figure ??? depicts the configuration settings which are explained in details below.

Recommenders' Model Repository Preference Page

Model Repository:

The URL of the model repository Code Recommenders searches for new recommendation models when accessed.

Enable Auto-Download:

If enabled, recommenders downloads suiteable recommendation models automatically. If unchecked no attempts are made to download models from the server.

Clear Caches:

All previously downloaded models are cached locally under ${workspace}/.metadata/.plugins/org.eclipse.recommenders.rcp/repository/ . When Clear cache is pressed, this directory is deleted. Files that could not be deleted are marked for deletion and will be deleted on Eclipse shutdown. All models are downloaded again automatically on next access.

Note

It is recommended to restart Eclipse after clearing the local caches.