[vtk-developers] VTK Deprecation Syntax

[Brad King]

Hello all,

Due to the significant changes to VTK since 4.4 there is a need to
deprecate methods in several VTK classes.  In the past this has been
done with a VTK_LEGACY_MACRO in the function body which gives a runtime
error.  There was also a macro VTK_REMOVE_LEGACY_CODE which if defined
would remove deprecated methods.  It was used like this:

class vtkMyClass
{
#ifndef VTK_REMOVE_LEGACY_CODE
   // Description:
   // DO NOT CALL.  Legacy code support method.
   void MyMethod();
#endif
};

#ifndef VTK_REMOVE_LEGACY_CODE
void vtkMyClass::MyMethod()
{
   VTK_LEGACY_METHOD(MyMethod, "4.2");
   // ... old function body ...
}
#endif

This approach has several problems.  First, it does not interact well
with wrapping.  The wrapper's parser is not aware of the
VTK_REMOVE_LEGACY_CODE macro.  Second, it does not give the application
any compile-time indication there is a problem and there was no way to
turn off the error other than turning off all errors.  Third, it
requires #if blocks in header files amongst documentation, which is ugly.

I suggest the following syntax as a replacement:

class vtkMyClass
{
   // Description:
   // DO NOT CALL.  Deprecated in VTK 5.0.
   VTK_LEGACY(void MyMethod());
};

#ifndef VTK_REMOVE_LEGACY_CODE
void vtkMyClass::MyMethod()
{
   VTK_LEGACY_BODY(MyMethod, "4.2");
   // ... old function body ...
}
#endif

or if the method is replaced with another:

#ifndef VTK_REMOVE_LEGACY_CODE
void vtkMyClass::MyMethod()
{
   VTK_LEGACY_BODY_REPLACE(MyMethod, "4.2", MyOtherMethod);
   this->MyOtherMethod();
}
#endif

The VTK_LEGACY macro can be defined by top-level VTK headers as one of
several choices:

#if defined(VTK_REMOVE_LEGACY_CODE)
# define VTK_LEGACY(x)
#elif defined(_MSC_VER) && _MSC_VER >= 1300
# define VTK_LEGACY(x) __declspec(deprecated) x
#elif defined(__GNUC__) && // ... GCC 3.1 or later
# define VTK_LEGACY(x) x __attribute__((deprecated))
#else
# define VTK_LEGACY(x) x
#endif

This will allow compile-time deprecation warnings on some compilers and
allow the method to be removed if VTK_REMOVE_LEGACY_CODE is defined.  It
is also easy to modify the VTK wrapping code to recognize this macro and
add the VTK_REMOVE_LEGACY_CODE preprocessor blocks around the wrapper
call to the method.  The wrapping code could then even include a
wrapping-language-specific warning to be generated.  Finally, the
Doxygen configuration can easily be modified to account for this macro.

Then VTK_LEGACY_BODY can be defined either as empty or to produce an 
error message based on some other setting such as 
VTK_LEGACY_ENABLE_MESSAGES or VTK_LEGACY_DISABLE_MESSAGES. 
VTK_LEGACY_BODY_REPLACE would producer a deprecation message similar to 
VTK_LEGACY_BODY but would also state what the replacement method is.

Comments?
-Brad