RE: Gtkmm documentation quality

["Dos Santos, Oliveira" <dossantos ebu ch>]

Hi Murray,

Yes, I agree with you, it's not useful into the official Gtkmm documentation but it demonstrates the 
implementation logics. I find that interesting :P

But I haven't yet find à way to identify the most useful functions of a class except my own experience and 
it's not enough... Doxygen is limited to classical classification patterns. 

It will be interesting to develop a tool to discover which Gtkmm class and then Gtkmm functions are the most 
used in graphical software development and establish some statistics to manage and display the documentation 
in a more efficient manner. Like a "google codeSearch/Koders/Gtkmm example/tutorial" sniffer/analyzer to 
generate the Gtkmm usage statistics and by extension all the GNOME libraries.

Regards

Marco Dos Santos Oliveira
EBU/European Broadcasting Union
Technology and Innovation Department

-----Original Message-----
From: Murray Cumming [mailto:murrayc murrayc com] 
Sent: vendredi 1 fÃvrier 2013 11:36
To: Dos Santos, Oliveira
Cc: 'Jiergir Ogoerg'; gtkmm-list gnome org
Subject: Re: Gtkmm documentation quality

On Thu, 2013-01-31 at 17:39 +0100, Dos Santos, Oliveira wrote:
> Hi,
>
> Currently I'm writing a non-developer documentation for an EBU open project using GTK/GTKmm and next week I 
> must improve the developer's documentation. I can add more rules in my doxygen configuration file and send 
> it next week. But we should define together (GTKmm community) which are the important criterias to increase 
> the quality of the documentation. Maybe several Doxygen's conventions will be required in the GTKmm's 
> source. 
>
> My doxygen file generates a documentation very similar to GTKmm Class Reference but with the Doxygen CSS 
> template.
> But it includes in plus : UML representation of my classes and data models. UML schematics for Calls and 
> Callers of each function. Functions can be sorted alphabetically or displayed in the same order than in my 
> source code... so when I write a class, I organize my declarations in consequence.
>
> Find as attachment my doxygen configuration file; It's based on an official example.

I don't think that UML diagrams of calls and callers would be particularly useful, because most of the 
implementation is in GTK+, not in gtkmm. Even for GTK+, they would be documentation of the implementation, 
not of the API.

--
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com

------------------------------------------------------------------------------

**************************************************
This email and any files transmitted with it are confidential and intended solely for the use of the 
individual or entity to whom they are addressed.
If you have received this email in error, please notify the system manager. This footnote also confirms that 
this email message has been swept by the mailgateway
**************************************************