Writing documentation is one of those tasks a programmer is typically not very keen about. Good and comprehensive documentation, however, is crucial for the success of open source software. But creating such documentation takes time and energy, is boring and has almost no immediate rewards. Consequently, documentation is (too) often incomplete - or even worse: outdated (meaning plain wrong) as this example shows:
I can't say what's more annoying: Having outdated and wrong documentation or having no documentation at all...
Some guys might postulate that well written (aka clean) code doesn't need any documentation - and they may be right. Others may argue that before documentation gets outdated it should be generated from code - since "the code is the design" this sounds reasonable too.
Based on this observation (and maybe driven by some project manager) a resourceful programmer came up with a tool that generates high-quality API documentation directly from code:
Impressive, right? I especially like its ability to take a statement such as "throws IllegalArgumentException" and create the JavaDoc comment "@throws the illegal argument exception"! Awesome. (OMG...)
No, seriously. Generating documentation using tools like
JAutodoc at most pleases our team lead since they improve the documentation ratio - from a programmer point of view this documentation is pretty useless.
OK, but what can Code Recommenders do about it? Can we improve it?
Yes. To some extent. In an
earlier post we described the idea of how example code that uses a framework's API could be leveraged to create valuable usage-driven documentation from, such as subclassing directives, which self-calls to execute, displaying code snippets showing common usages etc. If you haven't read this post before, you should reserve a few extra minutes to get the idea of mining documentation from example code.
However, mined documentation extracted from example applications is not the only information you want to leverage when using unfamiliar APIs. Often you refer to other resources on the web such as
tutorial sites, codesearch engines, or
code snippet repositories. So what you rather would like to have is this: A documentation platform, that tightly integrates various information into your IDE:
Something like this:
I'm extremely glad to announce that a first draft of this extended documentation platform is ready for download from the
Eclipse Markeplace. This platform has been developed by
Stefan Henss during this year's
Google Summer of Code. An outstanding work which I would like to present with this post.
The text below is copy of Stefan's final Project summary which I cross-post here:
Stefan Henss: Summing Up Eclipse ExtDoc (GSOC 2011)
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 on 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:
Disclaimer ;-)
Code Recommenders' Extended Documentation Platform is experimental - and so is the mined documentation shown for various Eclipse APIs. For 0.4 we are planning to add a community sourcing approach that enables us to support arbitrary frameworks.
Whatever comments you have (ranging from like to dislike), let us know about it. Here, in the forum or via
twitter.
Best,
Marcel, Stefan and Johannes.
