Hi All, Let me put this in a different way; how do we offer documentation concerning the "Amdatu API" to Amdatu developers? (With an "Amdatu developer" I mean a developer that builds components on top of the Amdatu platform). Does it even exist, this "Amdatu API"? In my opinion; yes, it does exist. It consists of a certain set of interfaces and utility classes. It is that set we want to define and document. So if I'm a Amdatu developer I would like to have some document describing _only_ the API. Do we agree on that?
Regards, Ivo -----Original Message----- From: amdatu-developers-bounces at amdatu.org [mailto:[email protected]] On Behalf Of Marcel Offermans Sent: woensdag 13 oktober 2010 0:11 To: amdatu-developers at amdatu.org Subject: Re: [Amdatu-developers] Package naming versus automated javadoc generation 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 _______________________________________________ Amdatu-developers mailing list Amdatu-developers at amdatu.org http://lists.amdatu.org/mailman/listinfo/amdatu-developers
