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
