GTK API documentation proposal for deprecated elements

[Hazael Maldonado Torres <gtk-documentation itxolutions com>]

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