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 > 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. > 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 <[email protected] > <mailto:[email protected]>> 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 <[email protected] > <mailto:[email protected]>> 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 [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
