Re: [gtkmm] API documentation: still aiming for 100%

[Matthew Walton <matthew alledora co uk>]

I've found a few things in the docs I can have a go at - there's a lot 
of stuff in GDK, but I don't feel I understand it well enough to have a 
go at that yet. gtkmm offers plenty of work though. One thing I would 
like to know though, if we need to override the automatic documentation 
for a method (I'm thinking specifically of Gtk::Dialog::add_button here, 
among others, because the docs don't cope with the overloaded version) 
can we just put a Doxygen block in the hg file or does it require magic 
elsewhere?

Murray Cumming wrote:
> I am reposting this for the people who missed it the first time. This is
> easy stuff that just needs a bit of your time. So far the response has
> not been great, though Billy O'Connor and Alberto Paro made some
> improvements.
>
> I added quite a lot of API documentation to the TreeView and TextView
> classes and associated classes, in gtkmm 2.4. For instance:
> http://www.gtkmm.org/docs/gtkmm-2.4/docs/reference/html/group__TreeView.html
>
> I think that 100% API documentation should be possible, and it's an easy way
> to help.
>
> Undocumented class methods are probably undocumented because
> - They are hand-coded because they use a different parameter order compared
> to the underlying C function. In this case you should look at the C docs and
> modify it accordingly. Look at the generated html of the C docs because not
> everything is in the .c files:
> http://www.gtk.org/api/
> - They are _MEMBER_GET() or _MEMBER_SET() accessors for struct fields. These
> needs little "Get the something" descriptions if there is nothing else to
> say.
>
> All classes should also have documentation for the class itself. Again, you
> can usually rephrase the C documentation for these.
>
> If you run "make doxygen-warnings" in gtkmm/docs/reference/, it will
> generate a text file with warnings about undocumented methods and classes.
> I'm not sure how complete that will be, but it's a start.
>
> I think we can reach 100%. That would be good.