[Dcmlib] [New feature] LEGACY/DEPRECATION mechanism

[Mathieu Malaterre]

> At 10:52 -0400 19/07/05, Mathieu Malaterre wrote:
> >Hello,
> >
> >   I have just finished integrating the deprecation mechanism VTK 
> >uses into GDCM. Here is how it works.
> >   On visual studio 6 and above, as well as on gcc 3.x and above 
> >there is an attribute you can specify to the function that let you 
> >mark as deprecated, therefore you can get compile time warning when 
> >you use such deprecated functions (instead of run time warnings). 
> >This make it very convienent to detect old API at compile time.
> >
> >   For developpers, you have to change in the header file:
> >
> >void foo();
> >
> >into
> >
> >GDCM_LEGACY(void foo());
> >
> >  in the implementation file:
> >
> >void bla::foo()
> >{
> >  // code
> >}
> 
> 
> --> I would like, at compile time, to warn user of DicomDir 
> constructor not to write any longer:
> 
> gdcm::DicomDir *d = new gdcm::DicomDir(name, true); // explore the 
> 'name' root directory
> or
> gdcm::DicomDir *d = new gdcm::DicomDir(name, false); // use the 'name' DICOMDIR
> 
> but
> gdcm::DicomDir *d = new gdcm::DicomDir();
> d->SetDirectoryName(rootDirectoryname); // explore a root directory
> d->SetLoadMode(load mode user wants, for parsing file headers);
> d->Load();
> 
> or
> gdcm::DicomDir *d = new gdcm::DicomDir();
> d->SetDirectoryName(existingDicomdirFilename); // parse the DICOMDIR object
> d->Load();
> 
> Actually, *everywhere* I'd like to warn users is this kind of case.
> Is it any exention for the following syntax?

That's intersting. Now we would have to duplicate the doc from doxygen
   @deprecated

into a MACRO that would dump code... 
As a temp solution why don't you just deprecate and do:

GDCM_LEGACY_REPLACED_BODY(Load(std::string), "1.2",
                          Load()); 

since what really changed from a function is it's signature. It would become a tad complicated if a function would call two deprecated functions, which one should we forward to ?
To keep it simple a would say a function is only deprecated into one function, and the documentation should provide more information on how to rewrite an old code.

Comments ?
Mathieu