One thing I've learned from reading the big reference on GObject documentation[1] is that howtos/quick refs/faqs and theoretical explanations don't, usually, mix. While reading it I usually wanted to know how and not why, therefore sometimes allot of information i would just skip, because it was not important to me at that given time. Skipping documentation is not really a good thing to do because sometimes what you really _need_ to know is mixed in between the things you don't. So, IMO, muppet's opinion would be appropriate if the text in question was a quick guide instead of a detailed discussion on how things are done. On Fri, 2004-08-27 at 01:57, Ryan McDougall wrote: > On Thu, 2004-26-08 at 08:14 -0400, muppet wrote: > > On Aug 26, 2004, at 3:33 AM, Ryan McDougall wrote: > > > > [spelling errors snipped] > > > > > by apologizing for digressing, you're digressing. how about a footnote > > or appendix instead? > > LOL. Its true that learning any sort of code requires a lot of parallel > learning, and the structure could be better. But sometimes it helps to > explain why we seem to be leaving the main point, then returning. > > > > > jumping straight into how do derive your own base object type without > > GObject, but still using GTypeInstance, is rather confusing. are you > > trying to show that you should do it yourself, or that this is the hard > > way to do it? remember that many people will skip the prose and jump > > straight to the code, so putting the example of a Hard Way and not > > necessarily the right way to do it first may be very misleading. > > Thats a really good point, maybe you could point out how I could make it > better. Maybe you could explain in the document why you chose GTypeInstance and why we use GObject instead. The same thing regarding to GTypeClass versus GObjectClass. Also, when G_DEFINE_TYPE_EXTENDED is introduced the reader should know the differences between these types, otherwise i think it's a bit confusing on why the object definition changed because of one macro. Wasn't the reader supposed to know how to define a class already? Why did the procedure changed? One more thing, introducing constructors before properties doesn't seem to be the best thing to do, because constructors are only used to check properties passed through the g_object_new marked with G_PARAM_CONSTRUCT. Therefore i think you should just introduce the user the _init method. Also why do you show _finalize and _dispose? For one thing readers will usually only use _finalize, another is that you don't explain the difference between them. So maybe first you could explain the _init and _finalize methods then explain properties and the go back and explain the _constructor. > > When writing this I had one main goal, teach myself GObject; and two > main assumptions, that each person learn differently, and there are more > than one tutorial available. > > That is the driving reason for the way it looks. I took the route that > made most sense to me: "How would I implement OO in C" and took GObject > as the given answer. In that sense its perfectly logical to pursue > Object Based programming (no derivation) before Object Oriented. > > A perfect example is your stated truism that all people will skip the > prose and go straight for the code. Its just not true because thats not > what I'd do. I want code *and* explanation, which is what I've given. > People who just want code can look else where for far shorter examples. > > I tried to state as much in the wording, but perhaps I've failed. Any > ideas? I am going to merge what I have with what Tiago has done, so > there will be more "How do I do X" later on. > > Cheers, > Ryan _______________________________________________ gtk-list@xxxxxxxxx http://mail.gnome.org/mailman/listinfo/gtk-list
