Documentation

[Matthias Clasen <matthias clasen gmail com>]

Hi,

if you're following git, you may have noticed that Jon and me have quite a few commits that only touch documentation, recently. I thought I should explain here what we this is about: We are trying to improve the developer documentation for application developers.

The reference documentation for the GTK+ stack may be extensive, but it is not easy to navigate and hard to make sense of if you are e.g. writing in _javascript_ and are not comfortable translating from C to _javascript_ in your head. The need to improve this situation has been discussed repeatedly: at the developer experience hackfest a year ago, and more recently at the Montreal summit. Now its time to do something about it !

Our short-term goals are to

- Make the doc comments more readable by moving from clunky docbook markup

  to markdown. This will help both for reading and updating the documentation in
  the sources, and for limiting the scope of whar our documentation-generating
  tools need to parse when generating online docs.

- Move from clear-text (like "free with gdk_rgba_free()") to annotations as much

  as possible, so we don't tell _javascript_ developers about memory management.

- Add language annotations to embedded examples.

- Generate the action (function-level) reference documentation with g-ir-doc-tool

  from the gir

We've started with GTK+ and GLib, but this effort should be easy to extend up and down the stack from here. Help is more than welcome!

Matthias