[mapguide-internals] Infrastructure for API deprecation

[Jackie Ng]

Hi All,

It seems that RFC9 (http://trac.osgeo.org/mapguide/wiki/MapGuideRfc9) has
caused mass confusion (I see discussions on the same topic almost every few
months, with pretty much the same answer: Use the new MgMap constructor!)

Although the documentation says the APIs mentioned in the RFC are
deprecated, there is no code-level constructs being generated (like
ObsoleteAttribute for .net or @Deprecated for java) that can easily raise a
warning flag to the MapGuide Developer that this method is deprecated and
should not be used.

If we intend to deprecate more APIs in the future, there will possibly be
more confusion as a result due to this limitation.

How possible is it to modify the SWIG/IMake infrastructure so that API
deprecation intent can be passed from the C++ level to the wrapper APIs? For
bonus marks, what about transferring doxygen comments from the C++ headers
to their wrapped counterparts?

For example, suppose we have a new C++ pre-processor marker: DEPRECATED_API

Applying it to a class like so:

class MgMap
{
    ...

    DEPRECATED_API:
        MgMap();
        virtual void Create(MgResourceService* resourceService,
MgResourceIdentifier* mapDefinition, CREFSTRING mapName);
        virtual void Open(MgResourceService* resourceService, CREFSTRING
mapName);
        void Save(MgResourceService* resourceService);

    ...
};

When processed by this theoretically modified SWIG/IMake infrastructure
produces the following wrappers:

For .net:

public class MgMap
{
    ...

    [ObsoleteAttribute("This member is deprecated. Please consult the API
documentation for alternatives")]
    public MgMap() { ... }

    [ObsoleteAttribute("This member is deprecated. Please consult the API
documentation for alternatives")]
    public void Create(MgResourceService resourceService,
MgResourceIdentifier* mapDefinition, String mapName) { ... }

    [ObsoleteAttribute("This member is deprecated. Please consult the API
documentation for alternatives")]
    public void Open(MgResourceService resourceService, String mapName) {
... }

    [ObsoleteAttribute("This member is deprecated. Please consult the API
documentation for alternatives")]
    public void Save(MgResourceService resourceService) { ... }

    ...
}

For java:

public class MgMap
{
    ...
    
    @Deprecated
    public MgMap() { ... }

    @Deprecated
    public void Create(MgResourceService resourceService,
MgResourceIdentifier* mapDefinition, String mapName) { ... }

    @Deprecated
    public void Open(MgResourceService resourceService, String mapName) {
... }

    @Deprecated
    public void Save(MgResourceService resourceService) { ... }

    ...
}

For PHP:

??? Does PHP even have code-level constructs to flag deprecation?



Thoughts?

- Jackie
-- 
View this message in context: http://osgeo-org.1803224.n2.nabble.com/Infrastructure-for-API-deprecation-tp5749868p5749868.html
Sent from the MapGuide Internals mailing list archive at Nabble.com.