[mapguide-internals] Infrastructure for API deprecation

[Jason Birch]

I don't think that PHP has code-level constructs for deprecated items.  When
they deprecate an internal API or feature (like they did for call-time pass
by reference), they make the method log a warning message when called, and
when it's removed it throws an error.

This wouldn't help our users much in the default installation (error output
turned off), but if they turn on error logging at least they'd see why
things aren't working.

Jason

On 17 November 2010 15:16, Jackie Ng wrote:

>
> 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.
> _______________________________________________
> mapguide-internals mailing list
> mapguide-internals at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
>