On 12 Oct 2010, at 12:30 , Ivo Ladage-van Doorn wrote: > The main point of the discussion seems to be the way we want to document our > API for developers building applications on top of Amdatu. Note that I am > really only talking about this particular use case. There are several options: > - Publish javadoc of all classes and mention 'somewhere' (where?) what > classes are part of the API and what are not. > - Publish javadoc of all classes and use package naming conventions like > ".api", "impl" and/or ".internal" to indicate what classes belong to the > public API. This is a common approach, used for example in the Jackrabbit and > Pax projects. > - Publish javadoc only for classes that are supposed to be part of the public > API.
There are other options: 1) Not publish any generated JavaDoc, but package the source code with the API. This also aids in debugging and all modern IDE's don't need JavaDoc anymore, they can generate it on the fly based on sourcecode. 2) Do as the OSGi compendium does, which is hand-write all specs and include relevant pieces of JavaDoc in those specs. > Concerning the remark; "The project object model is specifically intended to > hold such metadata and we can solve this in the maven build/release > configuration." > The point is that this is not as easy as it seems, which is the reason I > started this threat. If you do this in maven files, you will need a lot of > manual configuration which need to be changed as soon as a subpackage is > added or removed. Huh? The Maven files today already contain all the needed metadata, as they contain exact information about what packages should be exported. Re-iterating my point, that is the only thing needed, and adding any other tags or whatever would be redundant (and therefore error prone). > I don't see the real problem with using this special annotation. I do, it's redundant. Greetings, Marcel
