|
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: Βρείτε τον κατάλληλο υπολογιστή για εσάς. Μάθετε περισσότερα. |