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

[Murray Cumming <murrayc murrayc com>]

On Fri, 2004-03-05 at 09:35, Matthew Walton wrote:
> 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.

If you don't do anything, please at least mention it in a bugzilla bug,
with specific information.

>  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?

I think it's best to copy/paste/change the docs from gtk_docs.xml (the C
docs) to gtk_docs_override.xml.

I think you can also override the generated documentation by putting
doxygen comments into either the .hg or .ccg file (I forget. It uses an
obscure doxygen feature), but I would prefer to keep it centralised in 
gtk_docs_override.xml for now.
 
Thanks.

> 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.
-- 
Murray Cumming
www.murrayc.com
murrayc murrayc com