| Message ID | 1429644785-18264-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
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. On Tue, Apr 21, 2015 at 2:33 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > Signed-off-by: Mike Holmes <mike.holmes@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 >
On 21 April 2015 at 15:39, Bill Fischofer <bill.fischofer@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.holmes@linaro.org> > wrote: > >> Signed-off-by: Mike Holmes <mike.holmes@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 >> > >
I like the idea of a reason string on ODP_DEPRECATED(). On Tue, Apr 21, 2015 at 3:06 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > > > On 21 April 2015 at 15:39, Bill Fischofer <bill.fischofer@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.holmes@linaro.org> >> wrote: >> >>> Signed-off-by: Mike Holmes <mike.holmes@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 > > >
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.
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/api_guide_lines.dox | 4 ++++ 1 file changed, 4 insertions(+)