On Wed, Oct 13, 2010 at 9:42 AM, Ivo Ladage-van Doorn <Ivo.Ladage-vanDoorn at gxsoftware.com> wrote: > 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?
To be honest I am not even sure about that at this point ;) In any case I think it is a gros oversimplification to state that there will be one such thing as "The Amdatu API" for the "Amdatu Developer". If so my guess is that it would be low level and limited to OSGi platform, a (sub)set of OSGi compendium services, some Amdatu core services (tenants, users, provisioning, topology, context, ...?). IMHO it should be as lean and non invasive as possible . Then there are (and will be more) subprojects providing foundation services (eg. cassandra storage), frameworks (eg. opensocial), applications (eg educa) that will all have there own API, user documentation, howto's, faqs etc etc and they may very well (eventually but not so far away) have their own software lifecycle as well. I have a very hard time seeing that as "The Amdatu API" and why not let them all manage their own project information like http://repository.amdatu.org/sites/org.amdatu.platform-bundles/cassandra-application/index.html (within a set of conventions) for now? In terms of distributions one could argue that that if we release amdatu-opensocial-platform-1.0.zip (or whatever) at some point in time it would be nice to include the relevant jd in that, but that would be a simple case of aggregating them as part of that assembly/packaging process. And again, that could be done in maven, or we can split artifacts, or we can include it in the artifacts as Marcel suggested. But still note that this only makes some kind of sense because I think our goal is to use provisioning as are primary means of deployment and software configuration there is no fixed notion of what is or is not part of a specific deployment. To use an os metaphore: There is nothing in the linux kernel api documentation about higher level constructs such as a mysql database but at any point in time I can apt-get and use it (and the relevant documentation will be part of the package). Bottomline, I think we need to discover and consider what our "Amdatu API" is and what an "Amdatu Developer" needs before comitting to something like that and getting into javadoc bugs and how to solve and work around them. IMHO basic javadoc site generation and wiki documentation per sub project will suffice for now, see no need for some meta document (apart from the wiki) and certainly no need to commit to strange/redundant/invasive conventions at this point. regards, Bram -- ?Before a Strategist can be victorious, he must first know Himself, the Other and the Terrain? ?Sun Tzu > Regards, Ivo > > -----Original Message----- > From: amdatu-developers-bounces at amdatu.org > [mailto:amdatu-developers-bounces at amdatu.org] 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 > > _______________________________________________ > Amdatu-developers mailing list > Amdatu-developers at amdatu.org > http://lists.amdatu.org/mailman/listinfo/amdatu-developers >
