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

[Brian Cameron <Brian Cameron Sun COM>]

Mike:

> On Tue, 07 Dec 2004 14:09:46 -0600, Brian Cameron wrote:
>
> > I would also be very interested in dedicating time to improve the
> > overall developer documentation found on developer.gnome.org. 
>
> OK, just to clarify Sean and I weren't talking about API reference docs,
> more documentation on what libraries made breaking changes at which points
> so ISVs can get information relevant to backwards compatibility. It's a
> slight tangent to the API docs discussion :)

Right.  I did catch that, but I am also interested in working to generally
improve the developer documentation in GNOME, and not just API reference
docs.  In other words, getting better documentation about interface change
in libraries and applications from release-to-release would be very useful
to me.

However, I think that the gtk-doc tool might be a good place to document
library breakages.  Currently the gtk-doc tool doesn't provide the ability
to put comments in the code to highlight when interfaces change (when
structures change, when file-integration points change, when interaction
with environment variables change, when enumerations change, etc.).
Currently the only thing gtk-doc provides that is in this arena is
information about what release new function interfaces were added.

If gtk-doc were enhanced to provide more information about interface change,
then this might be a good way to document such change.  gtk-doc could
certainly be enhanced to provide good information about what interface
changes happened from release-to-release.

This would require enhancing gtk-doc to support new comment tags in the
source code, and probably enhancing gtk-doc to provide some additional
reports to highlight diffs from one release to the next.  But this is
probably a better way to document change than trying to keep such
documentation separate from the code, I'd think.  Also it just seems
more sensible to leveridge the existing tools that generate good docs
from the code so that it provides more information about change.

--

Brian