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 >> standard, >> 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 name clashes. Cheers, Axel. ------------------------------------------------------------------------------ This SF.net email is sponsored by: High Quality Requirements in a Collaborative Environment. Download a free trial of Rational Requirements Composer Now! http://p.sf.net/sfu/www-ibm-com _______________________________________________ Gtk2hs-devel mailing list Gtk2hs-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/gtk2hs-devel
