On 2/23/2013 1:34 PM, Richard Eckart de Castilho wrote: > Hi, > > thanks for the feedback. So, no javadoc, test-sources and test-javadoc > artifacts, ok. > I still do not get how the javadoc is built and published - see the comments > below. > >> On 2/22/2013 11:45 AM, Richard Eckart de Castilho wrote: >>> Hi there, >>> >>> I'm looking on reorganizing the uimaFIT build/release process to ramp up to >>> a first RC. >>> >>> Doing that, I notice that UIMA artifacts on Maven Central do not have >>> javadoc.jar test.jar and test-sources.jar. In past uimaFIT builds, we >>> included all of these. Is there any particular reason why these artifacts >>> are not generated, attached and deployed? >> Re Javadocs: There are 3 reasons, I think (maybe others can chime in...) >> >> The first is a granularity issue. We normally release Javadocs for the >> entire >> release, not just for one "module"; many of our released artifacts have >> multiple >> sub-projects, and we want to release one comprehensive Javadoc for all of the >> content. >> >> The second is to have a filtered Javadoc for users which only contains >> user-accessible methods we pay attention to keeping stable, and excluding >> internal-use, subject-to-change implementation methods. Often, but not >> always, >> this split can be done using Java's public/protected/package-private/private >> designation. To support this, we have a release-time step which builds the >> javadocs for the whole release, excluding "public" things which are not part >> of >> the user-api set. > The execution "javadocs-distr" in the "uimaj" POM (the one in trunk) runs the > "javadoc" goal, not the "aggregate" goal. That looks like only per-module > JavaDoc is generated. It appears to be the only place where the JavaDoc > plugin is configured. Where is the aggregate JavaDoc generated and how is > it later published?
This generates the aggregate javadoc. I recall, vaguely, that the aggregate goal assumed we wanted javadocs for everything, instead of just for the user-accessible APIs. To get the aggregate set generated, this goal has a configuration which includes specifying multiple "sourcepath" elements, one for each module that has user-referenced APIs. And then it also includes some otherwise-by-default-excluded packages that have the word "impl" in them (which is one of the naming convention we used for internal, implementation-detail, subject to change, etc., kind of packages). See the "excludePackageNames" element in the configuration for the javadoc in the POM. > >> The third is that tools like Eclipse can get the source from Maven (the >> source.jar) when needed for debugging, automatically. It's unclear (to me at >> least) the use case(s) that would make use of the JavaDocs-by-module on Maven >> central. > For Eclipse, the JavaDoc artifacts are indeed quite redundant, at least if the > sources are available. In principle, it could be imagined, though, that the > JavaDoc is post-processed and augmented, so that it contains more information > than the "plain" JavaDoc from the source. > >> Likewise, I'm not sure what the use-case(s) are for putting the test-sources >> on >> Maven Central. Tests are typically done during builds, and those are done >> typically by developers, who checked out the sources from SVN. > It's not a good practice, but it's possible to reference a test artifact from > module A so it can be used by the tests in module B. I'm not sure how this would work in practice. Normally, Maven dependencies refer to JAR artifacts (or compiled folders) that can be put into the classpath of something, like a test-runner. I don't see how putting a reference to a Maven-located artifact which was a "source" artifact would work? -Marshall > > Cheers, > > -- Richard >
