Introduction

The Eclipse Code Recommenders project [1] provides a intelligent code completion and API documentation for the Eclipse IDE. Basically, it tells you how to use a framework based on how people used it before you.

In my last year's GSoC, I have taken these code completions and integrated them into Javadoc for specific code contexts, e.g. “Which methods are frequently called together with m()”. Furthermore, I’ve developed an OSGi compliant stand-alone command-line application to enrich a project's Javadoc: Livedoc.

(Livedoc in action)

Livedoc by now is an Eclipse Incubator Project of Code Recommenders and works with Maven Repositories and coordinates. However, for the moment it only works following the paradigm: “One JAR at a time; no (cross-)referencing between multiple runs (resp. JARs)” But this limitation is going to fall now.

In this years GSoC, I'd like to develop a Livedoc [XXL] version, such that it becomes possile to create a large, interconnected web of documentation for different APIs (and in different versions).

For example, the (enriched) Javadoc for the Class SimpleMappedObjectViewer [2] in Eclipse EMF could link to the (enriched) Javadoc of Class TreeViewer in Eclipse JFace.

To make this easy for all Eclipse projects who want to take part in, I’d like to integrate Livedoc into a Maven (with or without Tycho) build, similar to the maven-javadoc-plugin.

Furthermore, I plan to make use of the new JDK 8 Javadoc Features for Livedoc (like the -Xdoclint function and the new DocTree API), support JDK 8 based JARs and implement an intelligent search similar to Android SDK’s Javadoc [3].

Features

I’d like to implement the following features for Livedoc and the Eclipse Community (in order of priority):

1. Compatibility to JDK 8 Projects

Make it possible for JARs based on JDK 8 to generate Livedoc for them. This does not involve additional features per se, but it does prepare Livedoc for the (near) future of Java. This will also include the usage of the -Xdoclint option of Javadoc.

2. Interconnect Javadocs of multiple projects / runs of Livedoc

This will be the main focus of my GSoC. I want to make it possible to create a large interconnected web of documentation for different APIs (in different versions). As a start, I plan to realize this with two different (but combinable) approaches:

• An automatic link discovery mechanism, based on meta-information in a project’s pom.xml (distributionManagement/site element). This is similar to the Apache maven-javadoc-plugin’s way of dealing with this issue (see also [4] and [5]).
  
• Use a base urls for Javadoc references, like help.eclipse.org or download.eclipse.org, and from there an ongoing name scheme for link creation (including bundle’s symbolic name, version, etc.)

A first showcase (or prototype, if you will) will be the Javadoc for Livedoc itself and its dependencies to Eclipse Code Recommenders and (of course) the JDK.

3. Allow aggreagated Livedoc runs for N projects at once.

With this feature (using the new Javadoc Access API of JDK 8), it will be possible to generate Javadoc documentation of multiple JARs with Livedoc at once, in a pure OSGI way. This means you can either:

• Run Livedoc as a stand-alone command-line application,
• Or use it as an OSGI Bundle in your host-application, with a programmatic API like the Javadoc API itself.

In both ways you can of course extend Livedoc with your own plug-ins, there are extension-points for that. Include your own statistics and informations, if you want to.

4. Integration into Eclipse CBI and provide Livedoc for other Eclipse projects

After the implementation of the third milestone, I’d like to share the features of Livedoc with a broader eclipse community.

My plan is to contact other Eclipse projects (arranged with and through my GSoC Mentor @ Code Recommenders) and ask them, how the Livedoc Maven Plugin should / could be used and easily integrated into their build.

My vision goal is to enable the possibility of Livedoc being the standard documentation generator for Eclipse projects.

Dependent on how successful / promising these will be, I plan to continue with the optional milestone 5. Maybe this will happen parallel to milestone 4.

5. A “search box” for Javadoc (Optional)

Javadoc out of the box has no search function at the moment. When looking at the Android SDK documentation [3], you may notice the little search icon at the upper right corner. Try it out, e.g. with “Location” as search term:

(Screenshot from [3])

Imagine this for your own Javadoc page, automatically generated within your Javadoc (resp. Livedoc) run.

Not only making documentation access for developers to your API much more comfortable, this should also decrease the time needed by new contributors to orient themselves in your codebase.

I plan two possible implementations through plug-ins for this:

• A simple search for Java Types (and maybe methods / class fields), realized  on client-side only through Javascript code, running in your browser and using a simple JSON index, which is pre-built during Livedoc generation.
  This approach is non-dependent to 3rd party implementations.
  
• An integration of Google’s Custom Search Engine [6], using the RESTful API [7]. This would provide a full-text search of your Javadoc without the need of an additional server backend, such as Apache Lucene [8]. Nevertheless, it has some limitations:

• User will have to provide his Google API Key & Custom Search Instance ID through a Livedoc parameter
• Dependent on Google’s Web services.
• Not entirely free, limited to Google’s Pricing:

“..., the API provides 100 search queries per day for free. If you need more, you may sign up for billing in the Cloud Console. Additional requests cost $5 per 1000 queries, up to 10k queries per day.”

At this point, I will try to contact Google (resp.  Carol Smith) and ask for a higher quota for testing and showcase purposes in my GSoC.

Milestones and Timeline

My GSoC consists of 4 milestones, each with an encapsulated feature description.

I want to provide a stable milestone release after each implementation phase, so I decided to include a testing phase between the milestone implementations and releases. At the moment, Livedoc contains a test-framework for generating non-mocked valid Javadoc ClassDoc instances [9], which can be uses as test data. I’d like to enhance this feature to make it possible for future Livedoc developers to test their own Livedoc extensions.

Gantt Timing Chart

About me

I'm a computer science student at the Darmstadt University of Technology and  Eclipse Commiter of Livedoc, a Code Recommenders Incubator project.

I’ have been working for Code Recommenders as a Contributor since October 2012.

Until now, I’ve done some various bugfixes, and corrections in the frontend, improved the drag’n’drop provider ranking in the Extdoc View of Eclipse and worked out a documentation for the different code completion scenarios (method calls, overrides, annotations etc.) in Java and how we want to treat them in the future at Code Recommenders. Of course, I’ve also created Livedoc in my last year’s GSoC.

Please feel free to contact me for further informations on my work or my GSoC proposal:

Links

[1]

http://www.eclipse.org/recommenders/

[2] http://download.eclipse.org/modeling/emf/emf/javadoc/2.9.0/org/eclipse/emf/mapping/presentation/SimpleMappedObjectViewer.html

[3]

http://developer.android.com/reference/packages.html

[4]

http://maven.apache.org/plugins/maven-javadoc-plugin/examples/links-configuration.html

[5]

http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#detectJavaApiLink

[6]

https://developers.google.com/custom-search/

[7]

https://developers.google.com/custom-search/json-api/v1/overview

[8]

http://lucene.apache.org/core/

[9]

http://docs.oracle.com/javase/7/docs/jdk/api/javadoc/doclet/com/sun/javadoc/ClassDoc.html