Modules & Javadocs

[Dan Diephouse <da...@envoisolutions.com>]

In light of the recent discussion on cxf-user about bundling, I think we
have some changes to make to our modules.

I think we have two options:
1. Collapse api & core & common
2. Collapse api & common

I think #1 is the right way to go. I know that some people are big fans of
keeping the -api module around, but there are a couple of serious issues
with it.

The API module does not include all the classes that I would consider part
of the CXF APIs. For instance, the *ServerFactoryBeans and the transports
are excluded. But users will frequently use these APIs. This is a problem
from a documentation stand point. We are definitely supporting these APIs
(they're even documented! ;-)), but by not including them in the API module
users will be confused and have a harder time finding docs on them. We could
move in these extra classes to API, but that would drag in many unnecessary
classes and would a pain from a maintenance point of view. The other issue
is that the API includes several classes which we don't actually care to
support or keep static.

The API module isn't really achieve any of its goals at this point, which
makes me think we should just get rid of it. Also, instead of producing
javadoc for just the -api module, I think we should make a master javadoc. I
as a user definitely want to be able to browse things like the HTTPConduit
or ServerFactoryBean APIs, which isn't possible now.

If people are really concerned we could create an API javadoc which
explicitly includes/excludes classes. This is a maintenance nightmare
though. Maybe people have other ideas as well?

Regards,
- Dan

-- 
Dan Diephouse
Envoi Solutions
http://envoisolutions.com | http://netzooid.com/blog