DRY Doc Project News

April 13, 2009

Parse Textile Format in Java

I discovered an interesting MyLyn subproject today. It's called WikiText and let you parse common Wiki markup like Textile. You can easily generate an HTML output of a simple text with it:

Textile excerpt


h1. Congratulations!

You read a *textile* document.

Java code


import org.eclipse.mylyn.wikitext.core.parser.MarkupParser;
import org.eclipse.mylyn.wikitext.textile.core.TextileLanguage;

// ... skip ...
private String textileToHtml(CharSequence source) {
 MarkupParser parser = new MarkupParser(new TextileLanguage());
 return parser.parseToHtml(String.valueOf(source));
}
// ... skip ...

Result in HTML


<?xml version='1.0' encoding='utf-8' ?><html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
 </head>
 <body>
 <h1 id="Bravo">Congratulations!</h1>
 <p>You read a <strong>textile</strong> documentation.</p>
 </body>
</html>

Currently supported format:

  • Confluence
  • MediaWiki
  • TracWiki
  • TWiki

The project page also mentions that it should be easy to add new format to those parser. At this time, the only output format is HTML. Some other format are planned like Eclipse help format or DocBook.

WikiText is the kind of libs that should be a project on its own more than a small lib into a big framework. For now it benefits from a separate bundle which let you download it without the MyLyn stuff. But if no other client depends on it, it may disappear in MyLyn.

Posted at 10:10 in DRY Doc Project News, Software | | Comments (1) | TrackBack (0)

April 12, 2009

Choosing a Backend Language

Describe the criterion that will determine the back-end language of DRY Doc.

I'm Looking for something easy to deploy and to write for. The goal here is to simplify the life of people who's using or extending the software.

Ability to easily write plug-in for the application

There can be various type of plug-ins in DRY Doc. Categories which come to mind:

  • file finder:

    Provides the ability to fetch content from various sources like the file system or a specific source version control.

  • comments finder:

    Provides the ability to parse a comment node (like the comments on a class)

  • editor:

    Provides the ability to edit some kind of comments

  • project:

    Provides the knowledge to deal with a given kind of project like Java project, Ruby project and so on.

A plug-in can be a tedious thing to write because all the complexity of the application lay into them. The need to provide a simple and powerful interface is a very high priority. Apart from the API definition, the choice of the language can be an important factor for the success of the operation.

Java will let you enforce behavior through interfaces. With an integrated editor, it can be very easy to write a new plug-in by integrating extending some interface. On the other side, Java is a verbose language which can take long time to understand if not familiar with. It integrates scripting language like Python or Ruby through Java based interpreter. That can be a good things to let people write plug-ins in their favorite language.

On the other side, a functional language like Ruby or Python can let people write plug-ins with less code. Ruby is also known as a good tool to write DSL(Domain Specific Language). The Object Paradigm is probably not the most well suited to write a parser plug-in, a DSL can be of good thing to describe how to extract comment content from a file. A very good sample of such usage is the Textmate language grammar which let you define rules for syntax coloration of almost any programing language through simple regular expression.

I want to eliminate any language that can prevent to make the application portable. So C/C++/C# or Visual Basic are out scope. C based language can be portable, but as I often had the proof, it is not an out of the box feature.

Ability to take on existing library for generating documentation

It is necessary to rely on existing library for generating the viewable part of the documentation. They provide advanced linking functionality to ease the navigation. A tricky part of the work can be to insert action control in the generated documentation (add the ability to edit a custom method comment in a Java class for example). Anyway, DRY Doc focus on adding the ability to edit content of the generated document and to insert those modifications back to the source, not to generate the documentation itself. Documentation for Java should be generated with Javadoc through DRY Doc.

Write less code

Less line of code means that your application will be more readable by another human, easy to debug, and of course, quicker to write. I'm alone on this project, and the guys who will wrote plugin to extends or adapt DRY Doc behavior won't have a lot more time to get things done. So let's keep to a short meaningful syntax. Once again, writing less can be achieve following two strategies: using a lightweight language which impover concision over declaration or a declarative language with an editor that can do some work for you. However, the use of the editor will help you to write quicker than expected but reading the generated code can become a lot harder and longer because the business process is hidden behind a lot of language specific declaration.

Another way of writing less code is to use existing libraries which will handle some program complexity for you. The trap here is to use an almost suited library instead of a perfect match. It can result in writing a big wrapping code with dirty hack to obtains what you really want. It can obfuscate the overall architecture. My concern here will be, how can I integrate generated documentation with DRY Doc.

Write meaningful API

This point is related to the first one. The goal here is to be able to define a meaningful API which seems natural to implements. Ideally, this API should be complete enough to solve all the case and simple enough to achieving a plug-in without having to read a complete specification.

Deploy the application in a snap

This is the most important feature of any Apple crafted product, the first minutes will make you use the product for years. Just make this thing easy to install with no setup operation. Achieving this objective can be done by using another Apple mantra: "You craft the software, you know what is the best parameter for any configuration you provide". Those citations are from memory, I cannot find where I read it.

I will evaluate Java and Ruby

At the beginning I thought that Java will be the most well-suited language for this application because of its interface mechanism which let you define very clear API. The integration of Python and Ruby inside Java let me thought that I will earn some precious days by having out of the box integrated doc generator for Python and Ruby as well through JPython and JRuby. But from a recent research, I discover that Javadoc must be executed from the command line as well as pyDoc and RDoc. So the interest of using Java go down and raise the opportunity to study a lightweight language to do the job. I choose Ruby over Python because of its better web solutions as of today.

I already made a Java prototype which parse a Textile file (typically a more Ruby suited feature). This prototype let me discover a good plug-in architecture for locating a resource, then parse its content.

Now I will start a Ruby prototype about reading the documentation of a Java method, then get the source doc string, and update its content. The goal of this prototype is to have a complete cycle and to see if Ruby can provide good interface support, perhaps through a DSL.

The interest of both prototype about the choice of a language is that they use some weak part of the languages instead of their glorious capabilities.

Instinctively, which one would you choose ?

Posted at 15:49 in DRY Doc Project News | | Comments (0) | TrackBack (0)

April 09, 2009

Introducing DRY Doc

Introducing DRY Doc, a tool for modifying API documentation from a web interface and store them back to the sources.

DRY Doc is the subject of my final exam work. It started two weeks ago and will be ongoing until end of October 2009.

I decided to start an Open Source project which will improve the way API documentation is managed. The basic concerns is to leverage the API documentation completeness and precision, mostly at the begining of a project. I'm always surprise to see cool projects with a terrible doc, and the effort it seems to be to release a good API doc.

I would like to encourage the storage of the API documentation in the source code, but a good one. It can be great if some other guys can edit this kind of documentation. Perhaps that you already face this strange feeling of having an open bug opened by a tech writer which complains about a typo or a missing explaination for an obscure method in your API. What if this guy, a tech writer or a super-user could modify directly the faulty doc himself? You just avoid a bug report and improve the documentation. You win the fact that the modification stay in you source code and that it will be updated by the developer next time he makes a change to the code.

So, the goal of this project is to provide a two way API doc. First you generate the doc from the source code, then you write back any modification to it. The moto could be:

Generate API doc on day 1, make it good on day 2, maintains for ten more years.

For those of you who care about,  I'm finishing my studies in software engineering in Yverdon High School Of Engineering and Management (codename Heig-Vd). I'm doing those studies along my full-time job by VMware. So this work is likely to be a spare time job. It should take arround 600 hundred work hours.

Posted at 12:20 in DRY Doc Project News | | Comments (0) | TrackBack (0)