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. There are some cases such the GtkProgressBar that has a paragraph saying that some big changes were done in GtkProgressBar and GrkProgress and that GtkProgress had been deprecated completely. But is you access the GtkProgress reference manual you will notice that it still there, and that there is not a clear statement saying that it had been deprecated completely. In addition, books such the relatively new GNOME 2.0 Official Developer Guide, which I particularly think is a great book, may generate some confusion for new developers who based their development in the APIs explained in the book. The book is listed in the index page of the www.gnome.org that for me and others may mean the book is recent but in contrast the book has sections that are completely out of date like the chapter about Gnome that you will find that a huge amount of the classes explained in the book are now deprecated. I think that you guys are doing an amazing work with Gnome/Gtk but I think that in order to make your work more accessible for new developers many things need to be done. This is the main and only reason why I am suggesting these changes in the documentation. I will really appreciate the time you may take to read this email and the possible inclusion of some of these points in future releases of the Gtk documentation. Best regards. Hazael _______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
