From: Axel Simon <Axel.Simon@en...> - 2009-04-11 13:40:16
On Apr 8, 2009, at 13:52, Maurí cio wrote:
>>> I just submitted a patch bundle to gtk-devel
>>> adding signals to a couple classes of widgets.
>> I'm always happy if people help out with patches. However, one very
>> important aspect is that these patches have a certain quality
>> in particular, the documentation should not be missing.
> Is it okay to remove the documentation of the
> deprecated interface? Maybe this could make documentation
> smaller, and easier for users.
No, both interfaces should be properly documented. But we should
never add deprecated functions, so this should not be a problem. If
you convert the signals of a module to use the new 'Signal' data
type, then simply add the new signals, possibly using new names, and
leave the old signals as they are. Ideally, you'd add a DEPRECATED
pragma for each old signal, but this is so error-prone and so much
work that it is probably not worthwhile doing it by hand. Ideally,
you use the code generated by apiGen.
> I think more effort could
> focus on the standard code, and there's always the
> documentation of earlier versions available for
> deprecated code.
At one point we might choose to stop generating html documentation
for deprecated functions by using some haddock magic. We will always
export the deprecated names to some extend in order not to break
existing software. Thus, it is important not to rename the deprecated
signals, even if the new signals must have different names because of