On Tue, Nov 4, 2014 at 3:45 PM, Bill Fischofer <bill.fischo...@linaro.org> wrote: > Please take a look at the RFC patches I circulated for odp_buffer.h, > odp_buffer_pool.h, and odp_packet.h. These now serve as both executables > and doxygen source so the information is in one place.
Ok, I saw the two patches, but after sending the previous email. Whether to keep the doxygen annotation in the API or not is one of the aspects, it has its advantages and disadvantages. One of the lows is that the API headers that differ between platforms (odp_buffer.h and odp_buffer_pool.h are likely to do so) will be hard to compare from platform to platform. Also the documentation can diverge between platforms without being the case. Could be only formatting, not necessarily differences in design (it should not be if a platform is supposed to suport API vx.x.x). But anyway it lacks clarity from my point of view. Another aspect that was discussed is how to handle the need to inline APIs, Taras has done some work for that and he encountered some problems. I spent a couple of hours today too on this, I was intrigued, and I sent out a patch. Here is a link to in case it was missed: http://lists.linaro.org/pipermail/lng-odp/2014-November/004478.html /Ciprian > > The split discussion refers to where the platform-specific typedefs are > defined + the question of how inlined implementations of select APIs are > expressed. > > On Tue, Nov 4, 2014 at 7:15 AM, Ciprian Barbu <ciprian.ba...@linaro.org> > wrote: >> >> On Mon, Nov 3, 2014 at 5:47 PM, Taras Kondratiuk >> <taras.kondrat...@linaro.org> wrote: >> > A need to split out a clean API headers is being discussed again, so >> > pulling this thread up to remind what the previous attempt was. >> > >> > On 07/08/2014 05:55 PM, Mike Holmes wrote: >> >> We discussed this on a hangout, here are the results as a way forward >> >> on >> >> this 1 month old topic. >> >> >> >> >> >> Attendees: >> >> Bala >> >> Taras >> >> Maxim >> >> Santosh >> >> Marshall >> >> Mike >> >> Bill >> >> >> >> Actions required: >> >> >> >> Step one: >> >> Move odp/include to odp/platform/linux-generic/include, update the make >> >> files to suit. >> >> >> >> Step two: >> >> Pull the doxygen documentation back up to odp/doc/odp_xxx.dox out of >> >> the >> >> header files. >> >> >> >> General Rational: >> >> >> >> 1. Anecdotal evidence from previous projects suggests we will end up >> >> with per platform includes anyway >> >> Is this because of the need to inline and to have per-platform defines >> / typedefs ? >> >> >> 2. We are trying to accommodate splitting out the platform specifics >> >> on >> >> this thread, that is what has driven this issue so No.1 looks >> >> correct >> >> 3. Linux-generic is the reference implementation and by default it is >> >> what is built now so there is no change in observed bechavior. This >> >> includes the fact that the platform specifics show though, all that >> >> changes is that is it now clear that they are specific to that >> >> platform and no pretense that the default doc is is platform >> >> independent. >> >> 4. We reduce the directory structure complexity, no need to include >> >> odp/include for each platforms make file. >> >> 5. Other platforms already include Linux-generic to reuse its code so >> >> we are not adding any new paths to find the same headers for those >> >> cases, there is no impact if the Linux-generic is not needed. >> >> 6. The API documentation is still common, it can be stored once in >> >> odp/doc/odpxxxxx.dox, doxygen will tie this together with the >> >> headers found per platform. >> >> 7. Platforms are still free to add pages to augment the documentation >> >> with platform specifics. >> >> >> >> Negatives: >> >> >> >> 1. Documentation is no longer all kept right next to the definitions >> >> which is one reason to use doxygen in the first place. >> >> From my point of view, Doxygen is primarily helpful for having a nice >> rendered view of the documentation in html/pdf format. Having the >> documentation in the same place as the headers (whether it contains >> Doxygen tags or not) makes for a more comfortable view for the >> programmer who may not be always looking at the browser (those >> hardcore Linux guys :) So I think we should have separate dox file. >> >> >> 2. There is less enforcement of the API across platforms, hopefully >> >> mitigated by the ODP-validation test suite. >> >> >> >> >> >> >> >> On 3 July 2014 13:14, Mike Holmes <mike.hol...@linaro.org >> >> <mailto:mike.hol...@linaro.org>> wrote: >> >> >> >> Let me take a look, I will ping you offline to make sure I >> >> understand and replicate the issue correctly >> >> >> >> >> >> On 3 July 2014 06:26, Taras Kondratiuk <taras.kondrat...@linaro.org >> >> <mailto:taras.kondrat...@linaro.org>> wrote: >> >> >> >> On 06/26/2014 06:24 PM, Taras Kondratiuk wrote: >> >> >> >> As we have discussed during a call, I've tried to implement >> >> option #2 >> >> for several files, but looks like Doxygen is not happy if >> >> documented >> >> variable can't be found in its input files. I couldn't find >> >> a Doxygen >> >> option that controls this behavior. >> >> Mike, do you have some ideas how to workaround it? >> >> >> >> >> >> Mike, do you have some hints? >> >> >> >> >> >> >> >> >> >> -- >> >> *Mike Holmes* >> >> Linaro Technical Manager / Lead >> >> LNG - ODP >> >> >> >> >> >> >> >> >> >> -- >> >> *Mike Holmes* >> >> Linaro Technical Manager / Lead >> >> LNG - ODP >> > >> > >> > _______________________________________________ >> > lng-odp mailing list >> > lng-odp@lists.linaro.org >> > http://lists.linaro.org/mailman/listinfo/lng-odp > > _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org http://lists.linaro.org/mailman/listinfo/lng-odp
