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

[Krzesimir Nowak <qdlacz gmail com>]

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.