Re: [gtk-list] DOCUMENTATION

[ajam <ajam erols com>]

I think you're completely right.  The idea that you have to completely study
the header files in order to learn how to use the library doesn't make sense.
I personally feel that it is a great learning experience to do it, but it
shouldn't be a requirement.  Normally, I would say that it is very easy to
criticize, than to do something.  But in this case there is a good argument. ;-)

Although I've been programming, non-professionally, for sometime, GTK+ is the
first widget library I'd ever used.  I started using it, because I thought,
and I still feel, it is the most complete and simple widget library around.
But after you start getting deeper into it, you start hitting walls.  There
are way too many functions that are not documented anywhere.  I personally 
don't have all the time in the world like maybe other people.
And yes, I've gone to the header files and the code of different applications
to learn more, but my goal is not library development.  Instead, it is
application development.  The small amount of time that I have I want to spend
it in problems of my actual application, not trying to figure out something
that should be besides the point.

I see it as if I'm forced to go into electromagnetics (EM) for the first time
in order to develop Ohm's Law with the final purpose of analysing a stupid
circuit.  If you like EM, and I do, it is great, but it shouldn't be a
requirement.

I also feel that this is really why some people have come, and gone to QT or
even MOTIF.  I am personally getting more into MOTIF, because there is more
documentation.  It is easier to calculate how long reading a chapter is going
to take, than to stop and search indefinitely for a function.  I heard that a
book is being written, which is great;  but is that why the documentation
available to FTP'd dates back to September last year?  

I know I'm being a little bit sarcastic, but in reality I'm very thankful for
the times when people have answered my questions.  Still, I see this just like
the Y2K issue.  If capable people don't do something, it is going to bite us all
at the end.  More widget libraries are poping out every month, and putting out 
documentation is the only way that GTK+ will survive. :-)

Regards, ajam


Juergen A. Erhard wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
>
> Just been looking into GTK 1.1.1 (maybe 1.1.2 is out... had this one
> lying about for a couple days).
>
> Now, am I the only programmer who sometimes puts some comments in his
> code?  The gtkprogress.c, for example, sports exactly 5(!) comments.
> And this is counting the copyright header and one comment that
> consists of a row of '*'.
>
> How should *anyone* understand what's going on?  I can't...
>
> Wouldn't it be nice if we could at least say what a function
> *does*... and comment some of the more dynamic things (signals passed
> and such)... and maybe add it to gtk.texi (gtkprogress is *not* in
> there)... maybe even document it there.
>
> Face it: the documentation situation is *the* major problem GTK
> has... (especially compared to QT).  No, the tutorial doesn't cut
> it... *reference docs* are what an experienced developer needs in the
> long run.  I can't go through the tutorial every time I need the
> semantics of a certain function...
>
> I really thought this was gonna improve...
>
> Bye, J
>
> PS: "And what do *you* do for it?"  Well, I'd love to... but I really
> don't think my knowledge of GTK is intimate enough to do this in a
> realiable way (and when someone more experienced has to got over my
> stuff in the end, correcting many mistakes, he could just as well
> write it himself).
>
> - --
> Jürgen A. Erhard  eMail: jae@laden.ilk.de  phone: (GERMANY) 0721 27326
>    MARS: http://members.tripod.com/~Juergen_Erhard/mars_index.html
>               GTK - Free X Toolkit (http://www.gtk.org)
>         Win32 has many known work arounds. For example, Linux.
>
> -----BEGIN PGP SIGNATURE-----
> Version: 2.6.3ia
> Charset: noconv
> Comment: Processed by Mailcrypt 3.4, an Emacs/PGP interface
>
> iQEVAwUBNdEN0gIG66LugGzRAQFyzwf/RvOTswAzlrUbD41O3uTszFidSlC6S42J
> J086+49iGp8OrgDpf4p6cfqZrnv6CvGJwlI9/7uvSZv9HFxrckjO9HpqC9cSklot
> 239aA3bCirP4JzpyVywSyIi3pc5r/N8EXfVdkZR4Is5vvcVNr614XVtTX/cUXNgB
> rhgAvtPwRomYPj4EobkhVRt234OfocRIMiscpb5HErRqhC+qu1VsDrlENnVPeDLc
> 7gvX3UO/+stzfRU5WOiquUDTlgeSQ0Gjur7n43/wKtMCX70phVGFV5RxXsF7WtQQ
> TV1jRokSKYIWIgpC0nxFtEh9jnkS+GEXO777uMAky8lmZdWot240OQ=ªwt
> -----END PGP SIGNATURE-----
>
> --
> To unsubscribe: mail -s unsubscribe gtk-list-request@redhat.com < /dev/null