On 21 April 2015 at 15:39, Bill Fischofer <bill.fischo...@linaro.org> wrote:
> Looks good, however we should have some standards for why an API may be > deprecated and what should be done to document it. For example, an API may > be deprecated if it is superseded by another API that provides a more > complete function. Or it may be deprecated if there is agreement that it > is not being used or it cannot be implemented efficiently, etc. When an > API is deprecated, the doxygen should state clearly why this has occurred > and offer migration advice for applications that may be using it. > Deprecated APIs should probably also issue a warning (does ODP_DEPRECATED > already do this?) if an application uses them. > ODP_DEPRECATED will warn at compile time - it is defined as __attribute__((__deprecated__)) >From the gcc manual "The deprecated attribute results in a warning if the function is used anywhere in the source file. This is useful when identifying functions that are expected to be removed in a future version of a program. The warning also includes the location of the declaration of the deprecated function, to enable users to easily find further information about why the function is deprecated, or what they should do instead." I completely agree on documenting the change, and you just reminded me that we can add @deprecated to the doxygen as well so maybe we will have to update ODP_DEPRECATED <http://docs.opendataplane.org/linux-generic-doxygen-html/group__odp__compiler__optim.html#ga76d645458c64fb14622e94b5bceae186> to take a string to make it easy to hit both mechanisms with a single change. e.g. void foo(void) ODP_DEPRECATED("this was a rubbish api and it is Tuesday already so lets delete it"); > > On Tue, Apr 21, 2015 at 2:33 PM, Mike Holmes <mike.hol...@linaro.org> > wrote: > >> Signed-off-by: Mike Holmes <mike.hol...@linaro.org> >> --- >> doc/api_guide_lines.dox | 4 ++++ >> 1 file changed, 4 insertions(+) >> >> diff --git a/doc/api_guide_lines.dox b/doc/api_guide_lines.dox >> index 2bc63a1..f26ce38 100644 >> --- a/doc/api_guide_lines.dox >> +++ b/doc/api_guide_lines.dox >> @@ -187,6 +187,10 @@ This is one of the reasons why some features MAY be >> defined as OPTIONAL. >> While allowed, the proliferation of OPTIONAL features SHOULD be avoided >> to enable broad application portability across many implementations. >> At the same time, a “least common denominator” approach MUST NOT be >> taken as that defeats the purpose of providing higher-level abstractions in >> APIs. >> >> +@subsection odp_deprecated ODP DEPRECATED >> +A deprecated API will remain marked as such in the public API using >> #ODP_DEPRECATED for two release cycles for the #ODP_VERSION_API_MAJOR >> number. >> +For example an API marked as deprecated in 1.1.0 will still be present >> in 1.2.0 and removed in 1.3.0 >> + >> @section defaults Default behaviours >> When an API has a default behaviour it must be possible for the >> application to explicitly call for that behaviour, this guards against the >> default changing and breaking the application. >> >> -- >> 2.1.0 >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> > > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
_______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp
