Re: Ideas about improving gtk-doc

[Stefan Kost <kost imn htwk-leipzig de>]

Hi all,

I am generally very pro for enhancing gtk-doc. I am working at a univerity and
could try to get a student to do the improvements as diploma work (we are a
technical university).
It would just need a TODO file with enough agreed changes. Not that the one
start doing it all and then patches would not be accepted.

One thing that I would like to see is to use a little DHTML. (I am not sure
wether devhelp uses gecko or gtk-html - this would probably require gecko)
In older projects I used doxygen and the html output from it is unfortunately
heavily overloaded. By using DHTML gtk-doc could add things like "references"
and "referenced-by" section to symbols, which are hidden by default and could be
expanded (or viewed as a tooltip).

The other thing is that I really like dot graphs (for class hierarchy, but
collaboration graphs as well). But here again seems to be no conclusion is the
community as the patch was never accepted (couldn't we make that an configure
option).

The student could also do gtk-doc homepage and documentation, if there is some
agreenment that this would be fine.

Stefan

Brian Cameron wrote:
> 
> Some people might have noticed my recent discussion on the
> desktop-devel-list where I suggested some ideas about improving
> gtk-doc.  Refer here:
> 
>   
> http://mail.gnome.org/archives/desktop-devel-list/2004-November/msg00738.html
> 
> 
> So you don't have to read that email, I'll restate the parts of that
> email that relate to gtk-doc.
> 
> Here at Sun, we use the GNOME documentation generated by gtk-doc for our
> ARC (Architecture Review Committee) review process.  The ARC reviews the
> documentation to ensure that interfaces are changing in ways that
> support ABI compatibility, and the like.
> 
> Unfortunately the documentation that gtk-doc generates is not complete
> from an ARC perspective, and we here at Sun have to manually dig through
> the code to generate the missing bits.  This is very time-consuming, and
> it seems like a better approach might simply be to improve the gtk-doc
> application so that more interface information is captured.
> 
> Specifically, making it possible to document the following sort of
> interface information would be very useful:
> 
> + Making it possible to document changes to data structures, enumerations,
>   etc.  It is not uncommon for new data elements to be added to a data
>   structure or for new enumerations to be added since these sorts of
>   changes do not break ABI-compatibility.  Making it possible to highlight
>   such changes in the gtk-docs would make it more clear to the end user
>   how functions should be properly used for the version of the library
>   they are using.  It would also be useful to identify when enumerations
>   and data structures were added as interfaces to the library.
> 
> + Making it possible to document file interfaces, so if the code
>   depends on data being in a certain file location (such as in
>   /usr/share), this can be made visible in the documentation.  It
>   would be especially useful to document file locations that are
>   useful for integrating into the desktop.  This way users who read
>   the documentation will know where to install files to integrate
>   with the GNOME component model, themes, etc.
> 
>   For example, libgnome could document that it makes use of
>   /usr/share/locale/locale.alias in the gnome-i18n.c file.
> 
> + Making is possible for gtk-doc to generate a list of deprecated
>   or removed interfaces that includes the specific release information
>   about when the interface was deprecated or removed.
> 
> + Making it possible to label an interface's stability level so that
>   users of the interface can know whether or not the interface is
>   "stable" and not going to break in a minor-release or whether the
>   interface is "unstable" or "private" and is therefore not guaranteed
>   to work with future versions of the library.
> 
> I'm wondering if the gtk-doc community agrees that these sorts of
> improvements to gtk-doc would be beneficial to the community and to
> the quality of the generated documentation.  If there is an interest,
> I'd be delighted to work on improving gtk-doc to do these sorts of
> additional tasks.  First, though, it would be useful to discuss how
> such improvements would best be integrated into the current tool.
> 

-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -

begin:vcard
fn:Stefan Kost
n:Kost;Stefan
org:HTWK Leipzig;FB. IMN
adr:;;Postfach 301166;Leipzig;;04251;Germany
email;internet:kost imn htwk-leipzig de
title:Dipl. Informatiker
tel;work:+49341 30766440
tel;home:+49341 2253538
tel;cell:+49178 3183742
x-mozilla-html:FALSE
url:http://www.imn.htwk-leipzig.de/~kost/about.html
version:2.1
end:vcard