GNOME Bugzilla – Bug 87016
Not all classes have overview docs
Last modified: 2004-12-22 21:47:04 UTC
We don't reuse the GTK+ reference documentation for the classes themselves, just for the methods. Someone needs to look at every class (e.g. every *.hg file and add an appropriate Doxygen description. Many already exists. You should look at the gtk+ API reference (www.gtkmm.org) and reword it appropriately.
Created attachment 9701 [details] [review] Patch to add descriptions for several classes.
I noticed that the description of some classes has a small introduction text, e.g.: /** Alignment Container * Normally, a widget is allocated at least as much size as it requests, and,[...] Is there a greater purpose for the "Alignment Container" bit? It doesn't look very good in the doxygen output.
Doxygen uses the first sentence at the top of the page. There is no way not to have a first sentence.
Applied. I guess that this bug needs to stay open for other widgets.
I think you misunderstood me, look at the Gtk::Alignment documentation: http://gtkmm.org/gtkmm2/reference/html/classGtk_1_1Alignment.html It doesn't look very pretty with the two first words there.
I guess that a full stop would fix that. OK. Also, see item 11 here about highlighting: http://www.stack.nl/~dimitri/doxygen/faq.html
OK, thats the first part of the problem. The second part is that: "Alignment Container Normally, a widget is allocated at least[..]" Doesn't sound or look very good when you read it in English. I investigated and looked through the doxygen manual (sorry, can't find an online version) - it seems that you can add a brief comment with \brief, and it will stack nicely up on the top of the page, with a link to the detailed documentation. The brief comment is also used on the class-overview page. I think we should add this to all classes, if you agree, I can do it.
I was suggesting a full stop after "Alignment Container", so I don't understand what you mean. We already have brief comments at the top - they are the _first sentences_.
Ah. I didn't read the rest of the doxygen documentation, you don't need \brief when JAVADOC_AUTOBRIEF is turned on, which it is in gtkmm.
Created attachment 9708 [details] [review] Patch to add more descriptions.
Documentation for quite a few methods in widget.hg (and in some other files) have the old documentation notation, e.g.: //: Show a widget. Is there a reason why this hasn't been changed to the new syntax, or is it a bug?
They are probably bugs. But we really need to check whether the --enable--fulldocs feature is reusing appropriate documentation from GTK+ instead.
Applied. Uploaded docs. I guess that you are getting this from the GTK+ docs, right?
Right.
Closing this for now. There are probably still classes without docs, but no major ones. I just added lots for the Menu stuff.