Re: GTK API documentation proposal for deprecated elements

[Matthias Clasen <mclasen redhat com>]

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