Re: [Suggestion] Wikify the docs - Discussion!‏

[Bernd Robertz <bernd robertz online de>]

Hello all,

now I want also bring a part into this discussion.

I was on a small trip away from home, so I didn´t follow the whole
thread, but:

First I liked the idea of wiki for gtkmm.
But have to I agree to Krzesimir.
It is more efficency to create docs through the code direct instead of
create and then port them into another managing tool.

Of course wiki is more comfortable in some reasons so I like the idea,
but lastly, it would be more work to do.

But keep it up, the idea is still a good one.

Greetings

Bernd


Am Sonntag, den 20.12.2009, 10:54 +0100 schrieb Krzesimir Nowak:
> On Wed, 2009-12-16 at 18:40 +0200, sledge hammer wrote:
> > Hi,
> > 
> > I had a crazy thought today. Why not wikify the docs?
> 
> That most probably won't do - public wiki needs a time to maintain and
> moderate it and I suspect that gtkmm devs neither wants to nor have
> enough time to look after next another thing.
> 
> > Well, the docs aren't complete and many functions need more
> > documentation or code examples. Moreover, as I have been using the
> > online docs for almost a year now I have noticed some problems. Such
> > as(but not limited to):
> > 1. Most of the enums don't have documentation. A reader needs to open
> > the gtk+ docs and find the corresponding documentation.
> 
> That is the problem with docextract_to_xml.py script - it does not
> extract documentation for enums. It would be useful to have it fixed or
> maybe separate tool for getting enum docs could be written (but there
> are already too much tools - h2defs.py, docextract_to_xml.py, enum.pl
> and whole gmmproc stuff).
> 
> > 2. There are some function-documentation that tries to link to soming
> > else that doesn't exist. This obviously occurs from the automatic
> > generation of the docs. This "problem" is somewhat rare, but exists.
> 
> Then send a patch overriding this with a doxygen comment in sources.
> 
> > 3. Many function-doc is just copy&pasted from the gtk+ docs but
> > doesn't correspond 100% to the C++ bindings
> 
> Ditto.
> 
> > 4. Quite a few minor typos
> 
> Ditto.
> 
> > 5. Quite a few functions don't have documentation just because the
> > their name documentes them(eg Gtk::Widget::show())
> 
> Ditto.
> 
> > 6. Signals often don't have a documentation or they have a poor one.
> > Almost always they don't tell when they are emited or what they mean
> > etc
> 
> That is probably another docextract_to_xml.py's fault.
> 
> > These all can't be fixed by a few people(the devs). But they can
> > certainly be spotted by the users of the API. These users could on the
> > spot correct the problem. The problem usuallyhas an obvious
> > solution(eg a typo). This has the benefit that the bug tracker is not
> > cluttered for doc-requests. Also the changes take effect immediately
> > and you don't have to wait the person in charge of the docs to make
> > the change. Furthermore, these problems by their nature are really
> > small and insignificant so noone goes out of their way to post a bug
> > report on the tracker. Although small and insignifacant they take more
> > time to discover an answer(eg browse the gtk+ docs to see what an enum
> > does). I personally have discovered many problems like these but I
> > didn't file a bug report because it would be time-consuming.
> 
> If you found a problem and you didn't file a bug, then there is no
> problem.
> 
> > Also if the docs are wikified, other people may post a useful example
> > code for a function, thus enriching the docs. Or they may explain
> > different use-cases(maybe pointing in a separate wiki page). Also the
> > users, could insert "see also links" that point to relevant functions,
> > eg in Gtk::Widget::Show() "see also" would be Gtk::Widget::Hide().
> > There could be other improvements also.
> 
> This can be done as well in doxygen documentation. Or rather - it is
> done partially in famous gtkmm tutorial.
> 
> > Please post your opinions on the matter. I would like to hear from
> > regular users too. Maybe the devs will make this change if enough
> > people want it! Thanks for your time.
> 
> Sure, wiki could be done. But it will be unofficial. And I just think
> that better is to fix the documentation and stuff itself than creating
> completely something else that does not fix anything and creates another
> effort to maintain.
> 
> Krzesimir.
> 
> _______________________________________________
> gtkmm-list mailing list
> gtkmm-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtkmm-list