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.
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
