On Sun, 2005-02-20 at 01:01 +0000, Hazael Maldonado Torres wrote: >Hi guys, I am new on the list so forgive me if this is not the right >list to post this and also if I am doing wrong in proposing the >following. > >I am relatively new on the Gnome/Gtk world, I am a programmer who is now >trying to use Gnome/Gtk as development platform on the daily basis. > >By experience, I think that the best way to encourage new developers to >use Gnome/Gtk platform is by providing a good and precise documentation. >I have seen that the API documentation changes every new release and >that many functions are deprecated but kept because of backward >compatibility. I believe that not only the backward compatibility is >very important but also the use of the adequate and new API in new- >written code. > >The fact that all the deprecated elements are highlight in the API >documentation with the sentence "Warning: gtk_toolbar_unset_icon_size is >deprecated and should not be used in newly-written code." is good but >not sufficient at all because the user needs to scroll below the >synopsis to identify those deprecated elements. Also the default value >of properties are really important and need to be shown somewhere else >in order to provide an easy access. > >In the following link you will found a API documentation page for >GtkToolBar that I had modified. The changes are small but I believe they >are significant. The synopsis had been splitted two section, the first >one shows the current API which is the one that developers must use in >new-written code. The second section groups all the deprecated elements. >Also the properties section had been changed, now for each property you >will found its default value after the access mode value. > >http://itxolutions.com/proposal_gtk_api_doc/GtkToolbar.html > >It is important that the name on the function and properties are auto >descriptive and that most of the times it is not necessary to go to the >function/signal/property explanation. Therefore the synopsis must >provide more information in the first place. >
I like your mockup. Do you have a patch with the necessary gtk-doc changes ? Matthias _______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
