Hi,
I had a crazy thought today. Why not wikify the docs? Why
you ask? 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.
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.
3. Many function-doc is just copy&pasted from the gtk+ docs but doesn't
correspond 100% to the C++ bindings
4. Quite a few minor typos
5. Quite a few functions don't have documentation just because the their name
documentes them(eg Gtk::Widget::show())
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
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.
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.
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.
_________________________________________________________________
Νέα Windows 7: Βρείτε τον κατάλληλο υπολογιστή για εσάς. Μάθετε περισσότερα.
http://windows.microsoft.com/shop
_______________________________________________
gtkmm-list mailing list
[email protected]
http://mail.gnome.org/mailman/listinfo/gtkmm-list
