Re: ARC & GNOME [Was: How we make decisions...]

[Sean Middleditch <elanthis awesomeplay com>]

On Tue, 2004-12-07 at 17:17 -0600, Brian Cameron wrote:
> Sean:

> > If gtk-doc can notice interface change information, the tools should be
> > modified to raise utter hell when the interface *does* change, because
> > it shouldn't.  Ever.  Not until the 3.0 series.
> 
> gtk-doc isn't really written to automatically notice change in interfaces.

Right.  I'm saying that if it was modified as your proposed, *then* it
should play interface-cop as well.

> Let me know if the attached scripts are at all useful to you.  They are
> what we use to try and verify library compatibility from release-to-release.

I wrote something very similar (albeit smaller in scale, intended for a
single library) for some other projects a couple years back.  The
problem is that, of course, this only checks symbols.  The tool needs to
check locally allocated, accessed, and/or modified structures and
classes, function arguments, public constants, and so on.

I think the kind of system you describe with what you'd like to see gtk-
doc do is similar to the (absolutely wonderful) PHP library
documentation.  It describes every function, its uses, relevant public
constants and behaviors, and notes the versions of the library in which
not only the function is available, but the versions of the library that
some of the optional or additional features became available in.  I have
never seen an API documentation system as useful as PHP's - it's
certainly something to emulate as much as possible, IMO.