ashkelon is an open source project. It is a Java API documentation tool designed for Java developers. Its goals are the same as the goals of the well-known javadoc tool that comes with J2SE, whose user interface most java developers are quite familiar with (see: http://java.sun.com/j2se/javadoc/ if you'd like to learn more about javadoc)
ashkelon addresses the following issues that javadoc does not:
ashkelon is a multi-api documentation system, unlike javadoc which produces single-api documentation
ashkelon's documentation system leverages SQL to provide a queriable/searchable repository for documentation
The DHTML GUI produced by ashkelon (which works with Mozilla 1.x or IE 5.x or IE 6.x browsers) is markedly different from the defacto html 3.2 user interface produced by javadoc, which i call "classic."
ashkelon's user interface is a Java web application, not a set of static html pages
The javadoc tool is composed of two parts:
- The documentation generator, used to produce html (or other) documentation
- a graphical user interface used to browse and peruse through the documentation (static html pages)
Sometimes the same person performs both the generation and referencing the documentation. however, the more common case is that of an api publisher producing javadocs for the api user who references them.
Similarly, ashkelon is also composed of two parts:
- the repository manager, used to populate (and otherwise manage) a database with documentation information
- The viewer application, a web application that provides access to the documentation in a variety of ways (search, browse, cross-reference, etc..). this app is in some ways markedly different from javadoc's user interface.
In an intranet environment, a development team needs to reference a number of APIs from a number of sources, including:
- Internal company code
- Sun APIs (J2SE, J2EE, etc..)
- Popular third party APIs (from Apache, Sourceforge, or other)
A developer may be appointed to the task of administrator. This individual would be in charge of using the repository manager to populate the ashkelon database with the API documentation. Alternatively, this person may choose to automate the task entirely and enhance the nightly build process to automatically rebuild the ashkelon repository with the latest docs.
The entire development team would use the viewer application as its window into the documentation. One of the strengths of ashkelon is the various ways in which someone can access information about a Programming Element:
- Hierarchical navigation to a target class or method
- Search by name
- Search by wildcard
- Navigating programmatic relationships
- Cross referencing classes or interfaces
- Power search feature (search by meta information such as author, modifier (et al) or a combination thereof
An important difference with ashkelon is that as an administrator, you will use the repository manager repeatedly to add new APIs into the repository. You don't have to (and should not try to) add all APIs in one step.
In an internet environment, it is conceivable that a single high-availability site be made available to the general Java developer community. Such a site might provide API publishers with online tools to register and populate their APIs in this "global" repository. The end-result would be publicly-accessible Java API documentation for many APIs which would be constantly kept up-to-date by the various API publishers.
