[PATCH 2/2 v2] compat: add compatibility definitions for old MM_MODEM_BAND_EUTRAN_* values

[Ben Chan]

On Wed, Jun 28, 2017 at 1:46 AM, Aleksander Morgado
<aleksander at aleksander.es> wrote:
>
> On Wed, Jun 28, 2017 at 9:36 AM, Ben Chan <benchan at chromium.org> wrote:
> > When adding this compat header, I noticed that __attribute__((deprecated)),
> > which G_DEPRECATED_FOR is based on, can't be associated with macros.  Both
> > gcc and clang associated the attribute to the next identifier found after
> > the macro definition, not the macro itself:
> >
> > #1
> >     G_DEPRECATED_FOR(NEW_ENUM)
> >     #define OLD_ENUM NEW_NUM
> >     void foo() {}   // __attribute__((deprecated)) is applied to foo()
> > instead of OLD_ENUM
> >     foo();  // this triggers a deprecation warning
> >
> > #2
> >     G_DEPRECATED_FOR(NEW_ENUM)
> >     #define OLD_ENUM NEW_NUM
> >     struct bar;   // clang fails to apply __attribute__((deprecated)) here
> > and throws an ignored-attribute warning
> >
> > It seems like only MSVC supports deprecation attribute on macro definitions
> > via #pragma deprecated.  Enumerator attribute would be the solution, but
> > only gcc 6 or above (clang 3 or above) supports that. For example, we can
> > use unnamed enum to define deprecated enumerators like this:
> >
> >     enum {
> >         OLD_ENUM G_DEPRECATED_FOR(NEW_ENUM) = NEW_ENUM
> >     };
> >
> > Instead of relying on compiler support of enumerator attribute, I use a
> > `static const int` in this patch as a workaround:
> >
> >     G_DEPRECATED_FOR(NEW_ENUM)
> >     static const int OLD_ENUM = NEW_ENUM;
> >
> > We can eventually migrate to use enumerator attribute when that is widely
> > supported by the default toolchain.  I also posted patches to fix the
> > G_DEPRECATED_FOR annotations in libqmi and libmbim.
>
> I just realized we lost documentation for the compat symbols when this
> new logic is introduced... See e.g. how the symbols were documented
> for libqmi:
> https://www.freedesktop.org/software/libqmi/libqmi-glib/latest/libqmi-glib-API-break-replacements.html
>
> If you rebuild with gtk-doc enabled, the new documentation doesn't
> show those any more. Maybe we need to add them explicitly in the
> sections file?
>

It seems to me that gtk-doc doesn't deal with `static const`
definitions. One silly workaround is to do something like this:

    /**
     * OLD_ENUM:
     *
     */
    G_DEPRECATED_FOR(NEW_ENUM)
    static const int DEPRECATED_OLD_ENUM = NEW_ENUM;
    #define OLD_ENUM DEPRECATED_OLD_ENUM

WDYT?


>
> --
> Aleksander
> https://aleksander.es